onebot-agent 0.2.0
Minimal single-agent gateway with ACP backends, skills, and messaging adapters
License: MIT
Requires Python: >=3.11

# onebot

`onebot` 是一個以 Python + uv 打造的精簡 single-agent 框架，支援：

- CLI 與 Web（FastAPI + Uvicorn）
- Telegram / LINE 作為訊息 I/O
- Skills（相容 OpenClaw / SKILLS 的 `SKILL.md` 規範）
- ClawHub skill 搜尋 / 安裝（透過官方 `clawhub` CLI）
- ACP backend 切換：`gemini --acp`、`copilot --acp`、`claude-code-acp`
- MCP servers（透過 ACP backend 傳入）

> PyPI distribution 名稱：`onebot-agent`（CLI 指令：`onebot`）

---

## 1) 需求

- Python 3.11+
- [uv](https://github.com/astral-sh/uv)

依你選的 backend，還需要：

- Claude：`claude-code-acp`（由 Python 套件安裝），以及 Claude CLI 已完成登入
- Gemini：`gemini` CLI（ACP 模式）
- Copilot：`copilot` CLI（ACP 模式）

若要使用 ClawHub skills：

- `clawhub` CLI（例如：`npm i -g clawhub`）

---

## 2) 安裝與開發

```bash
# 進入專案
cd onebot

# 安裝（含 dev）
uv sync --dev

# 看指令
uv run onebot --help
```

---

## 3) 快速開始

### 3.1 本地單次對話（ACP backend）

```bash
export ONEBOT_ACP_BACKEND=claude
uv run onebot chat "請幫我建立一個 hello.py"
```

切換 backend：

```bash
# Gemini
export ONEBOT_ACP_BACKEND=gemini
export ONEBOT_ACP_COMMAND=gemini
export ONEBOT_ACP_ARGS="--experimental-acp"

# Copilot
export ONEBOT_ACP_BACKEND=copilot
export ONEBOT_ACP_COMMAND=copilot
export ONEBOT_ACP_ARGS="--acp"
```

### 3.2 啟動 Web API

```bash
uv run onebot web --host 127.0.0.1 --port 18790
```

可用端點：

- `GET /`（Web 設定頁）
- `GET /health`
- `GET /skills`
- `GET /adapters`
- `GET /agents`
- `GET /config`
- `PUT /config`（更新設定並同步寫入 `.env` 與 `onebot_config.yaml`）
- `GET /conversations/{context_id}`
- `DELETE /conversations/{context_id}`
- `GET /logs`
- `GET /audit/events`
- `GET /mcp/tools`
- `POST /mcp/tools/check`
- `POST /line/webhook`
- `POST /auth/bootstrap`
- `POST /auth/login`
- `GET /auth/me`
- `POST /auth/logout`
- `GET /admin/users`
- `POST /admin/users`
- `POST /admin/users/{username}/deactivate`
- `GET /admin/bindings`
- `POST /admin/bindings/code`
- `GET /admin/whitelist`
- `PUT /admin/whitelist`

### 3.3 啟動 Telegram polling

```bash
export ONEBOT_TELEGRAM_TOKEN=<your-bot-token>
uv run onebot telegram
```

Telegram 綁定/群組規則（最小模式）：

- 私聊預設要求綁定（可關閉）
- 群組預設需 `@bot` mention 或 reply（可關閉）
- 管理員可在 Web 後台產生 6 位綁定碼，使用者私聊 Bot 傳送驗證碼完成綁定
- 可設定 telegram user/group 白名單與 onebot 系統帳號（含 NAS username 對應）

### 3.4 LINE webhook

1. 設定：

```bash
export ONEBOT_LINE_CHANNEL_SECRET=<secret>
export ONEBOT_LINE_CHANNEL_ACCESS_TOKEN=<token>
```

2. 啟動 Web：

```bash
uv run onebot web --host 0.0.0.0 --port 18790
```

3. 在 LINE Developers 把 webhook URL 設為：

```text
https://<your-domain>/line/webhook
```

---

## 4) Skills / ClawHub

列本地 skills：

```bash
uv run onebot skill list
uv run onebot skill list --all
```

搜尋 / 安裝 / 更新（透過 clawhub CLI）：

```bash
uv run onebot skill search "postgres backups"
uv run onebot skill install my-skill
uv run onebot skill update my-skill
uv run onebot skill update --all
```

進階 passthrough：

```bash
uv run onebot skill clawhub list
```

### 4.1 Agent Profiles（最小 AI 管理）

可在 `<workspace>/agents/*.md` 建立 profile（支援 YAML frontmatter 的 `name`/`description`），並透過 CLI 檢視：

```bash
uv run onebot agent list
uv run onebot agent show default
```

### 4.2 Conversation History（最小對話持久化）

```bash
uv run onebot chat "hello" --context cli
uv run onebot conversation show cli --limit 20
uv run onebot conversation reset cli
```

### 4.3 AI Call Logs（JSONL）

```bash
uv run onebot log tail --limit 20
uv run onebot log tail --adapter telegram
```

### 4.4 Bot 共用訊息管線（Line / Telegram）

- 兩個 adapter 現在共用 `BotMessageContext` 與 dispatch pipeline。
- 支援跨平台 `/reset`（或 `/新對話`）清除當前 context 對話歷史。

### 4.5 MCP Tool Catalog（可用性與前置檢查）

```bash
uv run onebot mcp list --all
uv run onebot mcp check search_knowledge query_project
```

### 4.6 Security / Audit（最小安全補強）

```bash
uv run onebot audit tail --limit 20
```

> 設定 `ONEBOT_SECURE_CONFIG_KEY` 時，`onebot_config.yaml` 內的 bot secrets 會以 AES-GCM 加密儲存（`.env` 仍保留明文以維持 CLI 相容）。

### 4.7 Web Admin（最小帳號/白名單管理）

1. 先啟動 `onebot web`
2. 首次使用可在首頁 Admin Console 按 `Bootstrap Admin`
3. 用 admin 帳號登入後可：
   - 建立/更新系統帳號（`admin|user`，可帶 NAS username）
   - 產生 Telegram 綁定碼
   - 設定 Telegram user/group 白名單

---

## 5) MCP 設定

透過 `ONEBOT_MCP_SERVERS` 以 JSON 陣列提供（會傳入 ACP backend）：

```bash
export ONEBOT_MCP_SERVERS='[
  {
    "name": "my-mcp",
    "command": "uvx",
    "args": ["my-mcp-server"]
  }
]'
```

> 注意：不同 backend 對 MCP 的支援程度不同（例如 Gemini 通常需要先在 CLI 內預先配置）。

---

## 6) 主要環境變數

- `ONEBOT_WORKSPACE`（預設 `~/.onebot`）
- `ONEBOT_ACP_BACKEND`：`claude|gemini|copilot`
- `ONEBOT_ACP_COMMAND`：覆寫 backend command
- `ONEBOT_ACP_ARGS`：覆寫 backend args（shell 字串）
- `ONEBOT_MCP_SERVERS`：MCP servers JSON 陣列
- `ONEBOT_MCP_TOOL_ALLOWLIST`：允許的 MCP 工具清單（逗號分隔；空值代表不限制）
- `ONEBOT_AGENT_PROFILE`：使用的 agent profile（預設 `default`，可在 `<workspace>/agents/*.md` 自訂）
- `ONEBOT_CONVERSATION_HISTORY_LIMIT`：每個 context 注入 prompt 的歷史訊息上限（預設 `20`）
- `ONEBOT_AUDIT_LOG_ENABLED`：是否啟用審計事件（預設 `true`）
- `ONEBOT_SECURE_CONFIG_KEY`：啟用 `onebot_config.yaml` secrets 加密（可選）
- `ONEBOT_ADMIN_BOOTSTRAP_USERNAME`：啟動時自動建立 admin（可選）
- `ONEBOT_ADMIN_BOOTSTRAP_PASSWORD`：啟動時自動建立 admin（可選）
- `ONEBOT_TELEGRAM_BINDING_REQUIRED`：是否要求 Telegram 綁定（預設 `true`）
- `ONEBOT_TELEGRAM_GROUP_REQUIRE_MENTION`：群組是否需 mention/reply 才觸發（預設 `true`）
- `ONEBOT_TELEGRAM_BINDING_CODE_TTL_MINUTES`：綁定碼有效分鐘數（預設 `10`）
- `ONEBOT_TELEGRAM_PERSONAL_AGENT_PROFILE`：Telegram 私聊預設 profile（預設 `default`）
- `ONEBOT_TELEGRAM_GROUP_AGENT_PROFILE`：Telegram 群聊預設 profile（預設 `default`）
- `ONEBOT_TELEGRAM_TOKEN`
- `ONEBOT_LINE_CHANNEL_SECRET`
- `ONEBOT_LINE_CHANNEL_ACCESS_TOKEN`

---

## 7) 測試與品質

```bash
uv run ruff check .
uv run pytest -q
```

---

## 8) 發佈流程（GitHub Release -> PyPI）

本專案已提供：

- `.github/workflows/ci.yml`：push / PR 執行 lint + test
- `.github/workflows/publish.yml`：Release published 時 build + publish

建議使用 PyPI Trusted Publisher（OIDC）：

1. 在 PyPI 專案設定 Trusted Publisher 指向本 GitHub repo/workflow
2. GitHub 建立 Release（Published）
3. workflow 自動 `uv build` 並上傳 `dist/*` 到 PyPI

---

## 9) 安全說明（目前）

- ACP 的檔案讀寫與終端執行有 workspace 限制與危險指令 deny patterns。
- 目前屬 MVP 安全層；高隔離場景建議後續加 Docker sandbox。