openclaw-skill/chapters/06-config.md

6. OpenClaw 設定參考

6.1 主設定結構 /root/.openclaw/openclaw.json

{
  "meta": { "lastTouchedVersion": "2026.2.25" },

  // Agent 預設設定
  "agents": {
    "defaults": {
      "model": {
        "primary": "google-antigravity/gemini-3-flash"
      },
      "workspace": "/root/.openclaw/workspace",
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 }
    }
  },

  // Telegram 頻道
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "<your-bot-token>",
      "dmPolicy": "pairing",   // 只有配對裝置可以 DM
      "groupPolicy": "allowlist",
      "streamMode": "partial"
    }
  },

  // Gateway 設定
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",  // 只接受本機連線，由 nginx 代理
    "auth": {
      "mode": "token",
      "token": "<access-token>"
    }
  },

  // 訊息設定
  "messages": {
    "ackReactionScope": "group-mentions"
  }
}

6.2 多 Agent / 多模型設定（獨立 Bot Token 方案）

踩坑紀錄（2026-02-24 ~ 02-25，v2026.2.17）

• 文件範例用 agentId，但實際 schema 要用 id（否則報 Unrecognized key: "agentId"）
• bindings 需要 match 包裝層，不是直接放 channel / accountId
• 新 Bot 必須先完成 config + 重啟 Gateway 後才按 /start，否則配對碼不會回傳
• 各獨立 agent 的 auth-profiles.json 不會自動共享，需手動複製
• （2026-02-25 新增） 當使用 accounts 區塊後，頂層 botToken 不再被當作獨立通道啟動。所有 Bot（包含主 Bot）都必須放入 accounts 內，否則 channels list 不會列出、provider 也不會啟動。主 Bot 建議使用 "default" 作為 accountId。
• （2026-02-25 新增） agents.list 只有具名 agent（如 life-assistant）時，隱含的預設 agent 不會掃描 workspace skills。必須在 agents.list 明確加入 main agent（含 workspace 路徑），並在 bindings 加入 { "agentId": "main", "match": { "channel": "telegram", "accountId": "default" } } 綁定。否則 workspace skills（如 daily-briefing）不會載入。

正確的 config 格式（已驗證可用）

{
  // 1. channels：所有 Bot Token 都放在 accounts 下
  //    頂層 botToken 在使用 accounts 後不再啟動為獨立通道
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "streamMode": "partial",
      "accounts": {
        "default": {                          // 主 Bot（@Cimon168_bot）
          "botToken": "<主 Bot Token>"
        },
        "life-bot": {                         // accountId，自訂名稱
          "botToken": "<新 Bot Token>"        // @Cimon_life_bot
        }
      }
    }
  },

  // 2. agents.list：用 "id" 不是 "agentId"
  //    主 agent 也必須明確列出，否則 workspace skills 不會載入
  "agents": {
    "list": [
      {
        "id": "main",                        // 主 agent，必須明確列出
        "name": "主 Agent",
        "model": { "primary": "cliapi/gpt-5.3-codex" },
        "workspace": "/home/selig/.openclaw/workspace"
      },
      {
        "id": "life-assistant",              // <- 必須用 "id"
        "name": "生活助理",
        "model": { "primary": "cliapi/gpt-5.3-codex" },
        "workspace": "/home/selig/.openclaw/agents/life-assistant"
      }
    ],
    "defaults": { "..." }
  },

  // 3. bindings：match 包裝層（channel + accountId 放 match 內）
  //    每個 account 都需要綁定到對應 agent
  "bindings": [
    {
      "agentId": "main",                    // 主 Bot → main agent
      "match": {
        "channel": "telegram",
        "accountId": "default"
      }
    },
    {
      "agentId": "life-assistant",           // 這裡用 agentId
      "match": {                             // <- 必須有 match 物件
        "channel": "telegram",
        "accountId": "life-bot"              // 對應 accounts 裡的 key
      }
    }
  ]
}

安裝步驟

# 1. BotFather /newbot → 取得 Token
# 2. 建立 agent 目錄
mkdir -p ~/.openclaw/agents/<agent-name>/{agent,sessions}
# 3. 修改 ~/.openclaw/openclaw.json（按上方格式）
# 4. 重啟 Gateway
systemctl --user restart openclaw-gateway
# 5. 確認 log 無錯誤
journalctl --user -u openclaw-gateway --since "30 sec ago" --no-pager
# 6. 在 Telegram 新 Bot 發送 /start → 取得配對碼
# 7. 配對
openclaw pairing approve telegram <CODE>

目前已部署的 Agent

Agent ID	Bot	用途	Model
main	@Cimon168_bot	工作/專案/協調	cliapi/gpt-5.3-codex
life-assistant	@Cimon_life_bot	生活安排	cliapi/gpt-5.3-codex

6.3 CLIProxyAPI 連線設定

CLIProxyAPI 作為 OpenAI-compatible proxy，讓 OpenClaw 可以使用多種 AI 帳號：

// 在 openclaw.json 加入 custom provider
{
  "models": {
    "providers": {
      "cliapi": {
        "baseUrl": "http://127.0.0.1:8317/v1",
        "apiKey": "<management-key>",
        "api": "openai-completions"
      }
    }
  }
}

CLIProxyAPI 管理介面：http://192.168.31.169:8317/management.html

6.3.1 CLIProxyAPI LLM 輪換規則

原始碼位置：sdk/cliproxy/auth/selector.go、config.yaml

輪換策略：Round-Robin（按請求次數）

不是依時間輪換，而是每一個 API request 進來就推進一格。

每個 (provider, model) 組合 → 獨立計數器 (cursor)
cursor → 每次請求 +1
選取：available[cursor % len(available)]

目前設定（/home/docker/CLIProxyAPI/config.yaml）：

routing:
  strategy: "round-robin"   # 另一選項：fill-first（固定燒第一個帳號）
request-retry: 3            # 失敗後最多重試 3 次（自動換下一個憑證）
max-retry-interval: 30      # 冷卻等待上限 30 秒
quota-exceeded:
  switch-project: true      # Quota 超限時自動切換帳號
  switch-preview-model: true

失敗重試（Fallback）

觸發條件（HTTP 狀態碼）：403 / 408 / 500 / 502 / 503 / 504

• 遇到錯誤 → cursor 繼續推進 → 下次自動選到不同憑證
• 不是獨立的「備援」邏輯，而是 round-robin 繼續走的自然結果

冷卻機制（Quota 超限）

• 憑證觸發 429 → 進入冷卻，指數退避（底數 1s，上限 30min）
• 冷卻中的憑證從可用池排除，round-robin 只從未冷卻憑證中選
• 冷卻時間到後自動恢復可用

活躍 Provider（目前）

Provider	模型類型
Grok (xai)	grok-4 系列、grok-code、grok-imagine
api.navy	qwen3.5、claude-sonnet-4.6、text-embedding

6.3.2 CLIProxyAPI 模型清單自動更新

當 CLIProxyAPI 新增/移除 AI provider 後，OpenClaw 不會自動偵測到新模型。需要更新 openclaw.json 中的 models.providers.cliapi.models 陣列。

自動更新腳本：~/clawd/scripts/refresh-llm-list.sh

# 手動執行
bash ~/clawd/scripts/refresh-llm-list.sh

# 排程：每週日 02:00（crontab）
0 2 * * 0 /home/selig/clawd/scripts/refresh-llm-list.sh >> /var/log/refresh-llm-list.log 2>&1

腳本流程：

1. 從 CLIProxyAPI /v1/models 取得最新模型清單
2. 依模型名稱自動分級（high/mid/low → 不同 cost 設定）
3. 備份 openclaw.json → openclaw.json.bak
4. 更新模型陣列，保留其他設定不變
5. 重啟 Gateway
6. 輸出差異（新增/移除的模型）

日誌：/var/log/refresh-llm-list.log

模型分級規則：

級別	關鍵字	input cost	contextWindow
high	opus, pro-high, thinking, codex-max, pro-preview	0.3	1M
mid	sonnet, grok, qwen, 預設	0.14	128K
low	haiku, flash-lite, embedding, mini	0.07	128K
GPT	gpt-*	0.2	128K

6.3.3 發送 Telegram 訊息（通知 Agent）

# 發送訊息到指定群組或用戶
sudo openclaw message send --channel telegram --target <chat-id> -m "訊息內容"

# 群組 ID 對照
# kaiwu（開物）：-5178404192
# tiangong（天工）：-5249018181
# yucheng（玉成）：-5296222979

# 範例：通知開物群組
sudo openclaw message send --channel telegram --target -5178404192 -m "preview 網站已上線"

# 附帶圖片
sudo openclaw message send --channel telegram --target -5178404192 -m "截圖" --media /path/to/image.png

# 靜音發送（不觸發通知音）
sudo openclaw message send --channel telegram --target -5178404192 -m "背景通知" --silent

6.4 Session Scope 設定

{
  "agents": {
    "defaults": {
      "session": {
        // 推薦：每個 Telegram 用戶獨立 session，防止資訊洩漏
        "dmScope": "per-channel-peer",
        // 每日 04:00 自動重置 session
        "reset": { "schedule": "0 4 * * *" }
      }
    }
  }
}

6.5 Auth Profiles（模型認證）

位置：/root/.openclaw/agents/main/auth-profiles.json

{
  "version": 1,
  "profiles": {
    "anthropic:manual": {
      "type": "token",
      "provider": "anthropic",
      "token": "sk-ant-..."
    },
    "cliapi:main": {
      "type": "api-key",
      "provider": "openai-compat",
      "apiKey": "<key>",
      "baseUrl": "http://127.0.0.1:8317/v1"
    }
  }
}

6.6 Heartbeat（心跳巡查）

Agent 定期自動觸發巡查，執行 HEARTBEAT.md 中定義的任務。

預設間隔（原始碼邏輯）：

• gateway.auth.mode = "oauth" → 1h
• 其他模式（token、local） → 30m

設定方式：

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m"    // 所有 agent 預設間隔（支援 "15m", "1h", "2h" 等）
      }
    },
    "list": [
      {
        "id": "main",
        "heartbeat": {
          "every": "15m"  // 個別 agent 覆寫
        }
      }
    ]
  }
}

指令：

# 查看目前設定
openclaw config get agents.defaults.heartbeat

# 修改全域間隔
openclaw config set agents.defaults.heartbeat.every "15m"

# 修改單一 agent（需知道 list index，如 main 是 index 0）
openclaw config set agents.list.0.heartbeat.every "20m"

巡查內容：定義在各 agent workspace 的 HEARTBEAT.md，例如：

• ~/.openclaw/workspace/HEARTBEAT.md（主 agent）
• ~/.openclaw/agents/life-assistant/HEARTBEAT.md（生活助理）

Telegram 頻道 heartbeat 可見性：

{
  "channels": {
    "telegram": {
      "heartbeat": "silent"  // "visible" | "silent" | "hidden"
    }
  }
}

6.7 Exec Approvals（指令執行審批）

Agent 執行 shell 指令（exec tool）時的安全策略。兩個地方都需要設定：

主控制：openclaw.json → tools.exec

這是真正的 policy 控制點，決定 agent 能否自動執行指令：

{
  "tools": {
    "exec": {
      "security": "full",   // "deny" | "allowlist" | "full"
      "ask": "off"           // "off" | "on-miss" | "always"
    }
  }
}

security	行為
deny	封鎖所有 exec（sandbox 預設）
allowlist	只允許白名單內的指令（gateway/node 未設時的預設值）
full	允許所有指令

ask	行為
off	永不詢問
on-miss	指令不在白名單時才詢問（預設值）
always	每次都詢問

# 設定指令
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
# 重啟 Gateway 生效
systemctl --user restart openclaw-gateway

輔助儲存：~/.openclaw/exec-approvals.json

儲存 allowlist（已核准的指令清單）和 socket 資訊，不是主要 policy 控制點：

# 查看
openclaw approvals get
# 設定（覆寫整個檔案）
openclaw approvals set --stdin < file.json

踩坑（2026-03-02）：只設定 exec-approvals.json 的 defaults.security=full + defaults.ask=off 不會生效。必須在 openclaw.json 的 tools.exec 設定才是真正的控制點。未設定 tools.exec 時，預設為 security: "allowlist" + ask: "on-miss"，導致 Telegram agent 每次執行指令都需要手動批准，而 Telegram 無法批准 → 120 秒超時。

Safe Bins（免審批的安全指令）

以下 stdin-only 工具即使在 allowlist 模式下也不需要白名單：

• jq, cat, head, tail, cut, uniq, tr, wc
• 可透過 tools.exec.safeBins 自訂
• 信任目錄：/bin, /usr/bin（可透過 tools.exec.safeBinTrustedDirs 擴充）