onebot-agent 0.1.2

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 /config
• PUT /config（更新設定並同步寫入 .env 與 onebot_config.yaml）
• POST /line/webhook

3.3 啟動 Telegram polling

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

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

---

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_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。