Skip to content
OpenClaw Docs

設定

OpenClaw 會從 ~/.openclaw/openclaw.json 讀取可選的 JSON5 設定檔。 有效的設定路徑必須是一個一般檔案。OpenClaw 的寫入操作不支援 openclaw.json 的符號連結配置；原子寫入可能會替換該路徑，而不保留符號連結。如果您將設定檔保留在預設狀態目錄之外，請將 OPENCLAW_CONFIG_PATH 直接指向真實檔案。

如果檔案不存在，OpenClaw 會使用安全的預設值。新增設定檔的常見原因：

  • 連接頻道並控制誰可以傳送訊息給機器人
  • 設定模型、工具、沙盒機制或自動化 (cron, hooks)
  • 調整工作階段、媒體、網路或 UI

請參閱完整參考以了解每個可用欄位。

代理程式和自動化工具應在編輯配置前使用 config.schema.lookup 取得確切的欄位層級文件。請使用本頁面取得以任務為導向的指引，並參閱Configuration reference以了解完整的欄位對映和預設值。

最精簡設定

Section titled “最精簡設定”
~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

編輯設定

Section titled “編輯設定”

bash openclaw onboard # full onboarding flow openclaw configure # config wizard

嚴格驗證

Section titled “嚴格驗證”

openclaw config schema 會列印出 Control UI 和驗證所使用的標準 JSON Schema。config.schema.lookup 會擷取單一路徑範圍的節點以及子摘要，以便用於深入工具。欄位 title/description 文件中繼資料會傳遞至巢狀物件、萬用字元 (*)、陣列項目 ([]) 以及 anyOf/oneOf/allOf 分支。當載入資訊清單註冊表時，執行時期外掛程式和通道的 Schema 會一併合併。

當驗證失敗時：

  • Gateway 無法啟動
  • 只有診斷指令可用 (openclaw doctor、openclaw logs、openclaw health、openclaw status)
  • 執行 openclaw doctor 以查看確切問題
  • 執行 openclaw doctor --fix (或 --yes) 以套用修復

Gateway 在每次成功啟動後會保留一份受信任的「最後已知良好」副本，但啟動和熱重新載入並不會自動還原它。如果 openclaw.json 驗證失敗 (包括外掛程式本機驗證)，Gateway 啟動將會失敗，或者會跳過重新載入，且目前的執行時期會保留最後接受的設定。執行 openclaw doctor --fix (或 --yes) 以修復加上前綴/被覆寫的設定或還原「最後已知良好」的副本。當候選項包含已編輯的秘密預留位置 (例如 ***) 時，將會跳過升級為「最後已知良好」的程序。

常見任務

Section titled “常見任務”
設定頻道（WhatsApp、Telegram、Discord 等）

每個頻道都在 `channels.

` 下有自己的配置區段。請參閱專屬的頻道頁面以取得設定步驟：

- [WhatsApp](/zh-Hant/channels/whatsapp) - `channels.whatsapp`
- [Telegram](/zh-Hant/channels/telegram) - `channels.telegram`
- [Discord](/zh-Hant/channels/discord) - `channels.discord`
- [Feishu](/zh-Hant/channels/feishu) - `channels.feishu`
- [Google Chat](/zh-Hant/channels/googlechat) - `channels.googlechat`
- [Microsoft Teams](/zh-Hant/channels/msteams) - `channels.msteams`
- [Slack](/zh-Hant/channels/slack) - `channels.slack`
- [Signal](/zh-Hant/channels/signal) - `channels.signal`
- [iMessage](/zh-Hant/channels/imessage) - `channels.imessage`
- [Mattermost](/zh-Hant/channels/mattermost) - `channels.mattermost`


所有頻道共用相同的 DM 政策模式：


```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}
```
選擇並配置模型

設定主要模型與可選的後備方案：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models 定義了型錄並充當 /model 的允許清單；provider/* 項目會將 /model、/models 和模型選擇器篩選為選定的供應商，同時仍使用動態模型探索。
  • 使用 `openclaw config set agents.defaults.models ’

’ —strict-json —merge來新增允許清單項目，而不移除現有的模型。會移除項目的純替換操作會被拒絕，除非您傳遞了—replace。 - 模型參照使用 provider/model格式（例如anthropic/claude-opus-4-6）。 - agents.defaults.imageMaxDimensionPx控制逐字稿/工具圖片的縮小比例（預設1200`）；較低的值通常會減少大量擷圖執行時的視覺 token 使用量。 - 請參閱 Models CLI 以在聊天中切換模型，並參閱 Model Failover 以了解認證輪替和後備行為。 - 關於自訂/自託管的供應商，請參閱參考資料中的 Custom providers。

控制誰可以傳訊息給機器人

DM 存取權透過 dmPolicy 依管道控制：

  • "pairing"（預設）：未知發送者會收到一次性配對代碼以供核准
  • "allowlist"：僅限 allowFrom（或已配對的允許儲存）中的發送者
  • "open"：允許所有傳入的 DM（需要 allowFrom: ["*"]）
  • "disabled"：忽略所有 DM

對於群組，請使用 groupPolicy + groupAllowFrom 或特定管道的允許清單。

如需每個管道的詳細資訊，請參閱 完整參考。

設定群組聊天提及閘門

群組訊息預設為需要提及。請為每個代理設定觸發模式。一般的群組/頻道回覆會自動發布；對於代理應決定何時發言的共用聊天室，請選擇訊息工具路徑：

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)
      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • 中繼資料提及：原生的 @-提及（WhatsApp 點擊提及、Telegram @bot 等）
  • 文字模式：mentionPatterns 中的安全 regex 模式
  • 可見回覆：messages.visibleReplies 可以全域要求使用訊息工具發送；messages.groupChat.visibleReplies 會針對群組/頻道覆寫該設定。
  • 請參閱完整參考資料以了解可見回覆模式、各頻道覆寫以及自我聊天模式。
限制各代理的技能

使用 agents.defaults.skills 作為共用基準，然後使用 agents.list[].skills 覆寫特定代理：

{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}
  • 省略 agents.defaults.skills 以預設啟用無限制技能。
  • 省略 agents.list[].skills 以繼承預設值。
  • 設定 agents.list[].skills: [] 以不使用任何技能。
  • 請參閱技能、技能設定以及設定參考資料。
調整閘道頻道健康監控

控制閘道以多積極的方式重新啟動看起來過時的頻道：

{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • 設定 gateway.channelHealthCheckMinutes: 0 以全域停用健康監控重新啟動。
  • channelStaleEventThresholdMinutes 應大於或等於檢查間隔。
  • 使用 `channels.

.healthMonitor.enabled或channels.

.accounts.

.healthMonitor.enabled` 來停用單一頻道或帳戶的自動重新啟動，而無需停用全域監控器。 - 請參閱健康檢查以進行操作調試，並參閱完整參考資料以了解所有欄位。

調整閘道 WebSocket 握手逾時

為負載較高或低效能主機上的本地用戶端提供更多時間以完成預先認證的 WebSocket 握手：

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}
  • 預設為 15000 毫秒。
  • OPENCLAW_HANDSHAKE_TIMEOUT_MS 對於一次性服務或 Shell 覆蓋仍具有優先權。
  • 優先修復啟動/事件迴圈停頓；此選項適用於健康但在預熱期間緩慢的主機。
設定會話與重設

會話控制對話的連續性和隔離性：

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
  • dmScope: main (共用) | per-peer | per-channel-peer | per-account-channel-peer
  • threadBindings: 繫結至執行緒之會話路由的全域預設值 (Discord 支援 /focus、/unfocus、/agents、/session idle 與 /session max-age)。
  • 請參閱 會話管理 以了解範圍、身分連結與傳送原則。
  • 請參閱 完整參考 以查看所有欄位。
啟用沙盒

在隔離的沙盒執行環境中執行代理程式會話：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

請先建構映像檔 —— 從原始碼檢出執行 scripts/sandbox-setup.sh，或是從 npm 安裝查看 沙盒 § 映像檔與設定 中內嵌的 docker build 指令。

請參閱 沙盒 取得完整指南，並參閱 完整參考 以查看所有選項。

為官方 iOS 版本啟用基於中繼的推送

基於中繼的推送預設使用託管的 OpenClaw 中繼：https://ios-push-relay.openclaw.ai。

若要使用自訂中繼，請在 gateway config 中設定：

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}

CLI 同等指令：

Terminal window
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

其作用如下：

  • 允許 gateway 透過外部中繼傳送 push.test、喚醒輕推 (wake nudges) 以及重連喚醒 (reconnect wakes)。
  • 使用由配對的 iOS app 轉發的註冊範圍傳送權限 (registration-scoped send grant)。gateway 不需要部署範圍的中繼權杖 (relay token)。
  • 將每個基於中繼的註冊綁定至 iOS app 所配對的 gateway 身份，因此其他 gateway 無法重用儲存的註冊資料。
  • 讓本機/手動的 iOS 版本保持使用直接 APNs。基於中繼的傳送僅適用於透過中繼註冊的官方發行版本。
  • 必須與內建於官方/TestFlight iOS 版本中的中繼基底 URL 相符，以便註冊和傳送流量到達同一個中繼部署。

端對端流程：

  1. 安裝官方/TestFlight iOS 版本。
  2. 選用：僅在使用自訂中繼部署時，在 gateway 上設定 gateway.push.apns.relay.baseUrl。
  3. 將 iOS app 與 gateway 配對，並讓節點 (node) 和操作員 (operator) 會話都連線。
  4. iOS app 會擷取 gateway 身份，使用 App Attest 與 app 收據向中繼註冊，然後將基於中繼的 push.apns.register 資料負載發佈至配對的 gateway。
  5. gateway 儲存中繼控制代碼 (relay handle) 和傳送權限，然後將其用於 push.test、喚醒輕推以及重連喚醒。

操作注意事項：

  • 如果您將 iOS app 切換至不同的 gateway，請重新連線 app，以便其發佈綁定至該 gateway 的新中繼註冊。
  • 如果您發布指向不同中繼部署的新 iOS 版本，app 會重新整理其快取的中繼註冊，而不是重用舊的中繼來源。

相容性注意事項：

  • OPENCLAW_APNS_RELAY_BASE_URL 和 OPENCLAW_APNS_RELAY_TIMEOUT_MS 仍可作為暫時性的環境變數覆寫使用。
  • 自訂 gateway 中繼 URL 必須與內建於官方/TestFlight iOS 版本中的中繼基底 URL 相符。
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍然是僅限回環 (loopback-only) 的開發緊急手段；請勿在設定中保存 HTTP 中繼 URL。

參閱 iOS App 了解端對端流程，以及 Authentication and trust flow 了解中繼安全模型。

設定心跳（定期檢查）
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: 持續時間字串 (30m, 2h)。設定 0m 以停用。
  • target: last | none | `

(例如discord, matrix, telegram, 或 whatsapp) - directPolicy: allow(預設) 或block` 用於 DM 風格的心跳目標 - 參閱 Heartbeat 取得完整指南。

Configure cron jobs
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention: 從 sessions.json 中修剪已完成的獨立執行階段（預設為 24h；將 false 設為停用）。
  • runLog: 修剪每項工作保留的 cron 執行歷史記錄列。maxBytes 仍然適用於較舊的檔案備援執行日誌。
  • 請參閱 Cron jobs 以瞭解功能概覽與 CLI 範例。
設定 Webhook (hooks)

在 Gateway 上啟用 HTTP webhook 端點：

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

安全性說明：

  • 將所有 hook/webhook payload 內容視為不受信任的輸入。
  • 使用專用的 hooks.token；切勿重複使用現有的 Gateway 驗證金鑰 (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD)。
  • Hook 驗證僅限標頭 (Authorization: Bearer ... 或 x-openclaw-token)；查詢字串 token 將被拒絕。
  • hooks.path 無法 /；請將 webhook 入口保留在專用子路徑，例如 /hooks。
  • 除非進行嚴格範圍的除錯，否則請停用不安全內容略過旗標 (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent)。
  • 如果您啟用 hooks.allowRequestSessionKey，也請設定 hooks.allowedSessionKeyPrefixes 以限制呼叫端選擇的 session keys。
  • 對於由 hook 驅動的代理程式，建議使用強大的現代模型層級和嚴格的工具原則 (例如僅限訊息傳遞，並在可能的情況下使用沙箱)。

查閱 完整參考資料 以了解所有對應選項和 Gmail 整合。

設定多代理程式路由

使用獨立的工作區和會話執行多個隔離的代理程式：

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

查閱 多代理程式 和 完整參考資料 以了解綁定規則和個別代理程式的存取設定檔。

將配置拆分為多個檔案 ($include)

使用 $include 來組織大型配置：

~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • 單一檔案：替換包含的物件
  • 檔案陣列：按順序深度合併（後者優先）
  • 同層級鍵：在包含之後合併（覆蓋包含的值）
  • 巢狀包含：支援最多 10 層深
  • 相對路徑：相對於包含檔案解析
  • 路徑格式：包含路徑不得包含空位元組，且在解析前後必須嚴格少於 4096 個字元
  • OpenClaw 擁有的寫入：當寫入僅變更由單一檔案包含（例如 plugins: { $include: "./plugins.json5" }）支援的 一個頂層區段時，OpenClaw 會更新該包含檔案並保持 openclaw.json 完整
  • 不支援的直寫：根包含、包含陣列以及具有同層級覆寫的包含，在 OpenClaw 擁有的寫入中會 失敗關閉，而不是扁平化配置
  • 限制：$include 路徑必須解析在持有 openclaw.json 的目錄下。 若要跨機器或使用者共享樹狀結構，請將 OPENCLAW_INCLUDE_ROOTS 設定為包含可能參考之 額外目錄的路徑清單（POSIX 上為 :，Windows 上為 ;）。 符號連結會被解析並重新檢查，因此詞法上位於配置目錄中但其實際目標逸出每個允許根目錄的路徑仍會被拒絕。
  • 錯誤處理：針對檔案遺失、解析錯誤、循環包含、無效路徑格式和過長長度提供明確錯誤

設定熱重新載入

Section titled “設定熱重新載入”

Gateway 會監視 ~/.openclaw/openclaw.json 並自動套用變更 - 大多數設定無需手動重新啟動。

直接編輯檔案在通過驗證之前會被視為不受信任。監視器會等待編輯器暫存寫入/重新命名的混亂情況平息，讀取最終檔案，並且在不重寫 openclaw.json 的情況下拒絕無效的外部編輯。OpenClaw 擁有的配置寫入在寫入前使用相同的架構閘道；破壞性的覆寫，例如刪除 gateway.mode 或將檔案大小縮減超過一半，都會被拒絕並儲存為 .rejected.* 以供檢查。

如果您看到 config reload skipped (invalid config) 或啟動時回報 Invalid config, inspect the config, run openclaw config validate, then run openclaw doctor --fix 以進行修復。請參閱 Gateway troubleshooting 查看檢查清單。

重載模式

Section titled “重載模式”
模式行為
hybrid (預設)立即熱套用安全變更。對於關鍵變更則會自動重新啟動。
hot僅熱套用安全的變更。當需要重新啟動時記錄警告 - 由您處理。
restart在任何配置變更時重新啟動 Gateway，無論是否安全。
off停用檔案監控。變更將在下次手動重新啟動時生效。
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

何者可熱套用 vs 何者需要重新啟動

Section titled “何者可熱套用 vs 何者需要重新啟動”

大多數欄位會在無停機情況下熱套用。在 hybrid 模式下，需要重新啟動的變更會自動處理。

類別欄位需要重新啟動？
頻道channels.*, web (WhatsApp) - 所有內建和外掛頻道否
代理與模型agent, agents, models, routing否
自動化hooks, cron, agent.heartbeat否
會話與訊息session, messages否
工具與媒體tools, browser, skills, mcp, audio, talk否
介面與其他ui, logging, identity, bindings否
Gateway 伺服器gateway.* (port, bind, auth, tailscale, TLS, HTTP)是
基礎架構discovery, plugins是

重新載入規劃

Section titled “重新載入規劃”

當您編輯透過 $include 參照的來源檔案時，OpenClaw 會根據 來源撰寫的佈局規劃重新載入，而非扁平化的記憶體內檢視。 這能讓熱重新載入決策（熱套用 vs 重啟）保持可預測，即使當 單一頂層區段存在於其個別包含的檔案中，例如 plugins: { $include: "./plugins.json5" }。如果來源佈局不明確，重新載入規劃將會失敗封閉（fails closed）。

Config RPC（程式化更新）

Section titled “Config RPC（程式化更新）”

對於透過 Gateway API 寫入配置的工具，建議採用以下流程：

  • config.schema.lookup 用於檢查單一子樹（淺層架構節點 + 子 摘要）
  • config.get 用於擷取目前的快照加上 hash
  • config.patch 用於部分更新（JSON 合併修補：物件合併，null 刪除，陣列替換）
  • 僅當您打算替換整個組態時才使用 config.apply
  • update.run 用於明確的自我更新加上重啟；當重啟後的工作階段應執行一次後續輪次時，包含 continuationMessage
  • update.status 用於檢查最新的更新重啟標記，並在重啟後驗證執行中的版本

代理程式應將 config.schema.lookup 視為取得精確 欄位級文件與約束條件的首選。當它們需要更廣泛的組態對應、預設值，或連結至專用 子系統參考資料時，請使用 Configuration reference。

部分修補範例：

Terminal window
openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

config.apply 和 config.patch 都接受 raw、baseHash、sessionKey、 note 和 restartDelayMs。當組態 已存在時，這兩種方法都需要 baseHash。

環境變數

Section titled “環境變數”

OpenClaw 從父程序以及以下來源讀取環境變數：

  • .env 從當前工作目錄（如果存在）
  • ~/.openclaw/.env（全域後備）

這兩個檔案都不會覆蓋既有的環境變數。您也可以在設定中設定內聯環境變數：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Shell env import (optional)

如果啟用且未設定預期的金鑰，OpenClaw 會執行您的登入 shell 並僅匯入缺失的金鑰：

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

Env var equivalent: OPENCLAW_LOAD_SHELL_ENV=1

Env var substitution in config values

使用 ${VAR_NAME} 在任何設定字串值中參照環境變數：

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

規則：

  • 僅匹配大寫名稱：[A-Z_][A-Z0-9_]*
  • 缺失/空的變數會在載入時拋出錯誤
  • 使用 $${VAR} 跳脫以取得字面輸出
  • 適用於 $include 檔案內
  • 內聯替換："${BASE}/v1" → "https://api.example.com/v1"
Secret refs (env, file, exec)

對於支援 SecretRef 物件的欄位，您可以使用：

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

SecretRef 詳細資訊（包括用於 env/file/exec 的 secrets.providers）位於 Secrets Management。 支援的憑證路徑列於 SecretRef Credential Surface。

如需完整的優先順序和來源，請參閱 Environment。

完整參考

Section titled “完整參考”

有關完整的逐欄位參考，請參閱 Configuration Reference。

相關：Configuration Examples · Configuration Reference · Doctor

相關

Section titled “相關”