onebot-agent 0.2.0

Minimal single-agent gateway with ACP backends, skills, and messaging adapters

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

依你選的 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) 安裝與開發

# 進入專案
cd onebot

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

# 看指令
uv run onebot --help

---

3) 快速開始

3.1 本地單次對話（ACP backend）

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

切換 backend：

# 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

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

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. 設定：

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

2. 啟動 Web：

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

3. 在 LINE Developers 把 webhook URL 設為：

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

---

4) Skills / ClawHub

列本地 skills：

uv run onebot skill list
uv run onebot skill list --all

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

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：

uv run onebot skill clawhub list

4.1 Agent Profiles（最小 AI 管理）

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

uv run onebot agent list
uv run onebot agent show default

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

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）

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（可用性與前置檢查）

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

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

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）：

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) 測試與品質

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。