理解設定結構

你是 OpenClaw 設定顧問。

【角色】
OpenClaw 設定顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 想改的設定：___
- 適用範圍：___
- 現有設定：___
- 是否團隊共享：___
- 經驗水平：___

【工作流程】
1. 梳理設定層級
2. 把設定放到合適層
3. 說明優先順序
4. 標出常見衝突
5. 給驗證

【輸出規範】
▌一、設定層級
▌二、設定歸層
▌三、優先順序
▌四、衝突 + 驗證

【硬約束】
- 設定放對層級
- 敏感設定安全存放
- 改後驗證生效
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

OpenClaw 的主設定檔是 ~/.openclaw/openclaw.json。它不是“所有欄位都填滿才專業”的大表，而是 Gateway、Agent、Channel、tools、models、sandbox、automation 的執行契約。

1. 先把設定理解成執行契約

openclaw.json 管的不是一個功能，而是多組邊界：

• Agent：workspace、skills、模型、bootstrap、sandbox。
• Channel：WhatsApp、Telegram、Discord、Slack 等入口。
• Session：不同人、不同群、不同賬號的上下文隔離。
• Tools 和 plugins：Agent 能呼叫哪些能力。
• Gateway：埠、認證、Control UI、記錄、熱載入。
• Automation：heartbeat、cron、hooks。

如果檔案不存在，OpenClaw 會使用 safe defaults（安全預設值）。真正需要設定，通常是因為你要接渠道、控訪問、設模型、開 sandbox、調 session 或加自動化。

flowchart TD
    Config["openclaw.json"]
    Gateway["Gateway 基礎設施"]
    Agent["Agent 工作單元"]
    Channel["Channel 訊息入口"]
    Tools["Tools / Plugins"]
    Automation["Automation"]
    Security["訪問與金鑰邊界"]

    Config --> Gateway
    Config --> Agent
    Config --> Channel
    Config --> Tools
    Config --> Automation
    Config --> Security

    style Config fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Security fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Agent fill:#dcfce7,stroke:#22c55e,stroke-width:2px

2. openclaw.json 必須是真實檔案

官方最新設定檔特別強調：active config path 必須是 regular file（普通檔案）。把 ~/.openclaw/openclaw.json 做成 symlink（符號連結）不適合 OpenClaw 自己寫設定，因為 atomic write（原子寫入）可能替換路徑，而不是保留 symlink。

如果你把設定放在預設狀態目錄之外，應該用：

OPENCLAW_CONFIG_PATH=/path/to/real/openclaw.json

3. 新手怎麼改設定

官方提供幾種入口：openclaw onboard、openclaw configure、openclaw config get/set/unset、Control UI，以及直接編輯檔案。

推薦順序：

1. 第一次用 onboarding。
2. 小改動用 openclaw config set。
3. 想看結構用 Control UI。
4. 需要查欄位約束時用 openclaw config schema 或 config.schema.lookup。
5. 已經理解 schema 時再直接編輯 JSON5。

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

Control UI 會從 live config schema 渲染表單，還能顯示欄位 title / description 等 docs metadata。對 Agent 或自動化工具來說，config.schema.lookup 是寫設定前的第一站。

4. strict schema 不是限制，是保護

OpenClaw 只接受完全匹配 schema 的設定。未知欄位、型別錯誤、非法值都會讓 Gateway 拒絕啟動；根級例外只有 $schema 字串，方便編輯器掛 JSON Schema metadata。

這聽起來嚴格，但對一個能呼叫工具、接訊息、處理金鑰的系統來說，這是保護。

設定校驗失敗時，優先跑：

openclaw doctor
openclaw config validate
openclaw doctor --fix

5. 最小設定只表達最小意圖

官方最小例子通常表達兩個核心意圖：給 Agent 一個 workspace，給某個 channel 一個受控入口。

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
    },
  },
}

這不是“推薦照抄上線”的完整設定。真實使用時，你還要根據平臺文件設定 token、allowlist、DM policy、群組策略、session、tools 和模型。

新手每次改設定前先問：

• 我接的是哪個渠道。
• 誰可以發訊息給它。
• 群組是否必須 mention。
• Agent 在哪個 workspace 工作。
• 這個入口能用哪些 tools 和 skills。
• 這次改動能不能單獨驗證。

6. 熱載入和重啟怎麼理解

Gateway 會監聽 openclaw.json，很多設定可以自動應用。預設 reload mode 是 hybrid：安全改動熱應用，關鍵基礎設施改動自動重啟。

常見 reload mode：

新手只要記住：儲存檔案不等於已經生效。要看 logs、health、doctor 和 Gateway 狀態。

7. 金鑰不要寫進公開設定

OpenClaw 會讀取父程序環境變數，也會讀取目前工作目錄 .env 和 ~/.openclaw/.env。這些檔案不會覆蓋已經存在的環境變數。

設定字串裡可以引用環境變數：

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

但環境變數引用不是加密。涉及 token、API key、Gateway auth、模型 key、OAuth 時，不要把明文寫進教學倉、公開 workspace 或截圖裡。

8. 設定壞了先做什麼

設定壞了不要先刪檔案重來。官方診斷入口包括 doctor、logs、health、status、config validate。

推薦排障順序：

1. 看 Gateway 是否還能啟動診斷命令。
2. 執行 openclaw config validate。
3. 執行 openclaw doctor。
4. 看記錄裡具體 schema path。
5. 需要自動修復時再跑 openclaw doctor --fix。
6. 回復最近一次設定改動。
7. 只修一個欄位，再驗證。

如果你一次改了十個欄位，就很難判斷真正壞在哪裡。

flowchart TD
    Broken["設定出錯"]
    Validate["openclaw config validate"]
    Doctor["openclaw doctor"]
    Logs["openclaw logs"]
    Fix["openclaw doctor --fix"]
    Small["只修一個欄位"]
    Status["openclaw gateway status"]

    Broken --> Validate
    Validate --> Doctor
    Doctor --> Logs
    Logs --> Fix
    Fix --> Small
    Small --> Status

    style Broken fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Small fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Status fill:#dcfce7,stroke:#22c55e,stroke-width:2px

9. 新手常見坑

• 直接複製完整設定，裡面的欄位自己並不理解。
• 把設定檔做成 symlink，又讓 OpenClaw 自己寫設定。
• 把明文金鑰放進 openclaw.json。
• 以為 workspace 是安全沙箱。
• 設定 open 入口後沒有 session 和 tools 限制。
• 儲存檔案後不看 reload 記錄。
• 一次改十幾個欄位，導致診斷沒有錨點。

10. 怎麼判斷設定健康

健康標準：

• openclaw doctor 沒有關鍵設定錯誤。
• openclaw health 能反映 Gateway 目前狀態。
• 每個 channel 都有明確訪問控制。
• 每個 Agent 都有明確 workspace。
• 金鑰來自環境變數或安全憑據，不在公開檔案裡。
• 改動範圍小，能透過記錄解釋為什麼生效。

設定的目標是讓 OpenClaw 可執行、可審計、可恢復，而不是把所有欄位填滿。

11. 本章自檢

1. 為什麼不建議把 openclaw.json 做成 symlink？
2. strict schema 校驗失敗時，Gateway 會怎麼處理？
3. 哪些設定通常熱載入，哪些通常需要重啟？

12. 接下來去哪

13. 官方資料

• Configuration
• Configuration reference
• Configuration examples
• Secrets management
• Environment variables