| name | oc-add-agent |
| description | Use when the user wants to add a new bot/agent to OpenClaw, or says '加 bot', '新增 agent', 'add agent', 'add bot', '多一個 bot', '再加一個'. |
oc-add-agent
Runtime Configuration
執行前讀取 setup.json：
- SSH 連線用
remote.sshAlias（以下以 ${SSH_ALIAS} 表示）
- 遠端路徑用
remote.openclawPath（以下以 ${OPENCLAW_PATH} 表示）
- 服務名稱用
gateway.serviceName（以下以 ${SERVICE_NAME} 表示）
- 現有 agents 從
agents 陣列取得
前置條件
確認 setup.json 存在且 onboarding.completed === true。如果沒完成 onboarding，引導使用者先完成。
步驟
1. 列出現有 agents
從 setup.json 讀取並顯示：
目前已設定的 agents：
1. main — 我的 Agent 🤖 (TELEGRAM_BOT_TOKEN_MAIN)
2. 引導 BotFather
一步一步說明（每步等使用者確認）：
- 打開 Telegram → 搜尋
@BotFather → 開始對話
- 輸入
/newbot
- BotFather 會問 bot 名稱 → 輸入想要的名稱
- BotFather 會問 username → 輸入獨特的 username（必須以
bot 結尾）
- 取得 token → 先複製起來，等下用
- 如果要在群組使用：
/setprivacy → 選你的 bot → Disable
3. 收集新 agent 資訊
- Agent ID：讓使用者取名（例：
assistant、helper），不可與現有 ID 重複
- Agent 名稱：使用者在 BotFather 取的名稱
- Emoji：讓使用者選一個
- Token 環境變數名稱：自動產生建議（
TELEGRAM_BOT_TOKEN_<ID大寫>），使用者可改
- Workspace 目錄名稱：預設和 Agent ID 相同
4. 更新本地檔案
4.1 config/openclaw.json
讀取現有 config，新增：
channels.telegram.accounts 加 entry：
"<id>_bot": {
"botToken": "${<TOKEN_ENV_VAR>}",
"name": "<agent 名稱>"
}
bindings 加 match rule：
{
"agentId": "<id>",
"match": {
"channel": "telegram",
"accountId": "<id>_bot"
}
}
agents.list 加 agent 定義：
{
"id": "<id>",
"identity": {
"name": "<agent 名稱>",
"emoji": "<emoji>"
},
"workspace": "${OPENCLAW_PATH}/workspace-<workspaceDir>"
}
驗證所有 token 欄位仍為 ${VAR} 格式。
4.2 secrets/openclaw.env.template
加入新的 placeholder：
<TOKEN_ENV_VAR>=<你的 Telegram Bot Token>
4.3 setup.json
在 agents 陣列加入新 entry：
{
"id": "<id>",
"name": "<agent 名稱>",
"emoji": "<emoji>",
"tokenEnvVar": "<TOKEN_ENV_VAR>",
"workspaceDir": "<workspaceDir>"
}
5. 建立 workspace 模板（LOCAL）
在 workspaces/<workspaceDir>/ 建立基本結構：
- 從第一個 agent 的 workspace 複製共用檔案（
USER.md、AGENTS.md、TOOLS.md、rules/behavior.md、docs/ROLECARD_SYSTEM.md、docs/EVOLUTION.md）
- 建立空的
SOUL.md、IDENTITY.md（讓使用者之後填寫）
- 建立
rolecards/ 目錄
6. 引導寫入遠端 token
告訴使用者需要在遠端加入新的 token：
ssh ${SSH_ALIAS} 'echo "<TOKEN_ENV_VAR>=<使用者貼上的 token>" >> ${OPENCLAW_PATH}/secrets/openclaw.env'
注意： token 只經過 SSH 傳到遠端，不存在本地。
7. 可選：自動部署
詢問使用者是否要立刻部署新 config：
- 是 → 執行
/oc-deploy 的流程
- 否 → 告知使用者之後可以用
/oc-deploy 部署
8. 完成摘要
列出所有已完成的動作和接下來可以做的事：
- 建議設定角色卡（
workspaces/<workspaceDir>/rolecards/）
- 建議設定身份（
workspaces/<workspaceDir>/SOUL.md、IDENTITY.md）
- 如果還要加更多 agent → 再次
/oc-add-agent
