oc-add-agent

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

一步一步說明（每步等使用者確認）：

1. 打開 Telegram → 搜尋 @BotFather → 開始對話
2. 輸入 /newbot
3. BotFather 會問 bot 名稱 → 輸入想要的名稱
4. BotFather 會問 username → 輸入獨特的 username（必須以 bot 結尾）
5. 取得 token → 先複製起來，等下用
6. 如果要在群組使用：/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