理解配置結構

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