跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw 會從 ~/.openclaw/openclaw.json 讀取選用的 設定。 作用中的設定路徑必須是一般檔案。OpenClaw 擁有的寫入不支援以符號連結形式配置的 openclaw.json； 原子寫入可能會取代該路徑，而不是保留符號連結。若你把設定保存在預設狀態目錄之外， 請將 OPENCLAW_CONFIG_PATH 直接指向真正的檔案。 如果檔案不存在，OpenClaw 會使用安全的預設值。新增設定的常見原因：
  • 連接頻道並控制誰可以傳訊息給機器人
  • 設定模型、工具、沙盒或自動化（cron、hooks）
  • 調整工作階段、媒體、網路或 UI
請參閱完整參考了解所有可用欄位。 Agent 和自動化應在編輯設定前使用 config.schema.lookup 取得精確的欄位層級文件。 此頁面提供以任務為導向的指引；更完整的欄位地圖與預設值請參閱 設定參考。
第一次設定？ 從 openclaw onboard 開始互動式設定，或查看 設定範例指南取得完整可複製貼上的設定。

​
最小設定

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

​
編輯設定

openclaw onboard       # full onboarding flow
openclaw configure     # config wizard

​
嚴格驗證

OpenClaw 只接受完全符合 schema 的設定。未知鍵、格式錯誤的型別或無效值會導致 Gateway 拒絕啟動。唯一的根層級例外是 $schema（字串），讓編輯器可以附加 JSON Schema 中繼資料。
openclaw config schema 會輸出 Control UI 與驗證使用的標準 JSON Schema。 config.schema.lookup 會為深入檢視工具取得單一以路徑為範圍的節點與子項摘要。 欄位 title/description 文件中繼資料會一路傳遞到巢狀物件、萬用字元 (*)、陣列項目 ([]) 以及 anyOf/ oneOf/allOf 分支。當 manifest registry 載入時，執行階段 Plugin 與頻道 schema 會合併進來。 驗證失敗時：
  • Gateway 不會啟動
  • 只有診斷命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
  • 執行 openclaw doctor 查看確切問題
  • 執行 openclaw doctor --fix（或 --yes）套用修復
Gateway 會在每次成功啟動後保留一份受信任的最後已知良好副本， 但啟動與熱重新載入不會自動還原它。如果 openclaw.json 驗證失敗（包含 Plugin 本地驗證），Gateway 啟動會失敗，或重新載入會被略過且目前執行階段會保留最後接受的設定。 執行 openclaw doctor --fix（或 --yes）以修復帶前綴/被覆寫的設定，或 還原最後已知良好副本。當候選設定包含已遮蔽的秘密佔位符，例如 *** 時，會略過提升為最後已知良好。

​
常見任務

每個頻道在 channels.<provider> 下都有自己的設定區段。設定步驟請參閱專屬頻道頁面：所有頻道共用相同的 DM 政策模式：
{
  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 和模型選擇器篩選到指定 provider，同時仍使用動態模型探索。
  • 使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 新增允許清單項目，而不移除既有模型。除非傳入 --replace，否則會移除項目的純取代會被拒絕。
  • 模型參照使用 provider/model 格式（例如 anthropic/claude-opus-4-6）。
  • agents.defaults.imageMaxDimensionPx 控制 transcript/tool 圖片縮小（預設 1200）；較低的值通常會降低大量截圖執行中的 vision-token 使用量。
  • 請參閱模型 CLI了解如何在聊天中切換模型，並參閱模型容錯移轉了解授權輪替與備援行為。
  • 自訂/自架 provider 請參閱參考中的自訂 provider。
DM 存取權會透過 dmPolicy 依頻道控制：
  • "pairing"（預設）：未知傳送者會取得一次性配對碼以供核准
  • "allowlist"：只允許 allowFrom 中的傳送者（或已配對允許儲存中的傳送者）
  • "open"：允許所有傳入 DM（需要 allowFrom: ["*"]）
  • "disabled"：忽略所有 DM
對於群組，請使用 groupPolicy + groupAllowFrom 或頻道專屬允許清單。各頻道詳細資訊請參閱完整參考。
群組訊息預設為需要提及。請為每個 Agent 設定觸發模式，並讓可見的聊天室回覆保持在預設 message-tool 路徑，除非你有意使用舊式自動最終回覆：
{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • 中繼資料提及：原生 @-mentions（WhatsApp 點按提及、Telegram @bot 等）
  • 文字模式：mentionPatterns 中的安全 regex 模式
  • 可見回覆：messages.visibleReplies 可以要求全域使用 message-tool 傳送；messages.groupChat.visibleReplies 會覆寫群組/頻道的設定。
  • 可見回覆模式、各頻道覆寫與自我聊天模式請參閱完整參考。
使用 agents.defaults.skills 作為共用基準，然後用 agents.list[].skills 覆寫特定 Agent：
{
  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 時，預設不限制 Skills。
  • 省略 agents.list[].skills 時，會繼承預設值。
  • 設定 agents.list[].skills: [] 表示沒有 Skills。
  • 請參閱 Skills、Skills 設定，以及 設定參考。
控制 gateway 對看似停滯的頻道進行重新啟動的積極程度：
{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • 設定 gateway.channelHealthCheckMinutes: 0 可全域停用健康監控重新啟動。
  • channelStaleEventThresholdMinutes 應大於或等於檢查間隔。
  • 使用 channels.<provider>.healthMonitor.enabled 或 channels.<provider>.accounts.<id>.healthMonitor.enabled，可在不停用全域監控的情況下，停用單一頻道或帳號的自動重新啟動。
  • 操作除錯請參閱健康檢查，所有欄位請參閱完整參考。
在負載較高或低功耗主機上，給本機用戶端更多時間完成驗證前 WebSocket handshake：
{
  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
      },
    },
  },
}
請先建置映像 - 若使用原始碼 checkout，請執行 scripts/sandbox-setup.sh；若使用 npm 安裝，請參閱沙箱 § 映像與設定中的內嵌 docker build 命令。請參閱沙箱以取得完整指南，並參閱完整參考了解所有選項。
relay 支援的推播在 openclaw.json 中設定。在 Gateway 設定中設定：
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
對應的 CLI：
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
這會做什麼：
  • 讓 Gateway 透過外部 relay 傳送 push.test、喚醒提示和重新連線喚醒。
  • 使用由已配對 iOS App 轉送、以註冊為範圍的傳送授權。Gateway 不需要部署範圍的 relay token。
  • 將每個 relay 支援的註冊繫結到 iOS App 配對的 Gateway 身分，因此另一個 Gateway 無法重用已儲存的註冊。
  • 讓本機/手動 iOS 建置維持直接 APNs。relay 支援的傳送僅適用於透過 relay 註冊的官方發佈建置。
  • 必須符合內建於官方/TestFlight iOS 建置的 relay base URL，讓註冊和傳送流量到達同一個 relay 部署。
端對端流程：
  1. 安裝使用相同 relay base URL 編譯的官方/TestFlight iOS 建置。
  2. 在 Gateway 上設定 gateway.push.apns.relay.baseUrl。
  3. 將 iOS App 配對到 Gateway，並讓 node 與操作員工作階段都連線。
  4. iOS App 擷取 Gateway 身分，使用 App Attest 加上 app receipt 向 relay 註冊，然後將 relay 支援的 push.apns.register payload 發佈到已配對的 Gateway。
  5. Gateway 儲存 relay handle 和傳送授權，然後將它們用於 push.test、喚醒提示和重新連線喚醒。
操作注意事項：
  • 如果你將 iOS App 切換到不同的 Gateway，請重新連線 App，讓它可以發佈繫結到該 Gateway 的新 relay 註冊。
  • 如果你發佈指向不同 relay 部署的新 iOS 建置，App 會重新整理其快取的 relay 註冊，而不是重用舊的 relay origin。
相容性注意事項：
  • OPENCLAW_APNS_RELAY_BASE_URL 和 OPENCLAW_APNS_RELAY_TIMEOUT_MS 仍可作為暫時的環境覆寫使用。
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍是僅限 loopback 的開發逃生口；不要在設定中保留 HTTP relay URL。
請參閱 iOS App 了解端對端流程，並參閱驗證與信任流程了解 relay 安全模型。
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every：期間字串（30m、2h）。設定為 0m 可停用。
  • target：last | none | <channel-id>（例如 discord、matrix、telegram 或 whatsapp）
  • directPolicy：DM 風格 Heartbeat 目標使用 allow（預設）或 block
  • 請參閱 Heartbeat 取得完整指南。
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention：從 sessions.json 修剪已完成的隔離執行工作階段（預設 24h；設定 false 可停用）。
  • runLog：依大小和保留行數修剪 cron/runs/<jobId>.jsonl。
  • 請參閱 Cron 工作，了解功能概覽和 CLI 範例。
在 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 token。
  • Hook 驗證僅限標頭（Authorization: Bearer ... 或 x-openclaw-token）；查詢字串 token 會被拒絕。
  • hooks.path 不能是 /；請將 Webhook 入口保留在專用子路徑，例如 /hooks。
  • 除非進行嚴格限定範圍的偵錯，否則請停用不安全內容繞過旗標（hooks.gmail.allowUnsafeExternalContent、hooks.mappings[].allowUnsafeExternalContent）。
  • 如果啟用 hooks.allowRequestSessionKey，也請設定 hooks.allowedSessionKeyPrefixes，以限制呼叫者選取的工作階段金鑰。
  • 對於 hook 驅動的代理，建議使用強大的現代模型層級和嚴格工具政策（例如僅限訊息傳遞，並在可能時加上沙箱）。
請參閱完整參考，了解所有 mapping 選項和 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 組織大型設定：
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • 單一檔案：取代所屬物件
  • 檔案陣列：依序深度合併（後者優先）
  • 同層金鑰：在 includes 之後合併（覆寫 included 值）
  • 巢狀 includes：最多支援 10 層深度
  • 相對路徑：相對於執行 include 的檔案解析
  • OpenClaw 擁有的寫入：當寫入只變更一個最上層區段，且該區段 由單一檔案 include 支援，例如 plugins: { $include: "./plugins.json5" }， OpenClaw 會更新該 included 檔案，並保持 openclaw.json 完整不變
  • 不支援的寫入穿透：root includes、include arrays，以及具有 同層覆寫的 includes，對 OpenClaw 擁有的寫入會以失敗關閉處理，而不是 攤平成設定
  • 限制範圍：$include 路徑必須解析到保存 openclaw.json 的目錄下。若要在多台機器或多個使用者之間共用樹狀結構，請將 OPENCLAW_INCLUDE_ROOTS 設為額外目錄的路徑清單（POSIX 上為 :，Windows 上為 ;）， includes 可參照這些目錄。符號連結會被解析並重新檢查，因此如果路徑在字面上位於設定目錄中， 但其真實目標逃逸出每個允許的 root，仍會被拒絕。
  • 錯誤處理：針對缺少檔案、解析錯誤和循環 includes 提供清楚錯誤

​
設定熱重新載入

Gateway 會監看 ~/.openclaw/openclaw.json 並自動套用變更 - 大多數設定不需要手動重新啟動。 直接檔案編輯在驗證前會被視為不受信任。監看器會等待 編輯器暫存寫入/重新命名的變動穩定，讀取最終檔案，並拒絕 無效的外部編輯，不會重寫 openclaw.json。OpenClaw 擁有的設定 寫入會在寫入前使用相同 schema gate；破壞性覆寫，例如 移除 gateway.mode 或將檔案縮小超過一半，會被拒絕並 儲存為 .rejected.* 以供檢查。 如果你看到 config reload skipped (invalid config)，或啟動回報 Invalid config，請檢查設定、執行 openclaw config validate，然後執行 openclaw doctor --fix 進行修復。請參閱 Gateway 疑難排解 取得檢查清單。

​
重新載入模式

模式行為
hybrid（預設）立即熱套用安全變更。對關鍵變更自動重新啟動。
hot只熱套用安全變更。需要重新啟動時記錄警告 - 由你處理。
restart任何設定變更都會重新啟動 Gateway，無論是否安全。
off停用檔案監看。變更會在下次手動重新啟動時生效。
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
什麼會熱套用，什麼需要重新啟動

大多數欄位都會在不中斷服務的情況下熱套用。在 hybrid 模式中，需要重新啟動的變更會自動處理。
類別欄位需要重新啟動？
頻道channels.*、web（WhatsApp）- 所有內建和 Plugin 頻道否
代理與模型agent、agents、models、routing否
自動化hooks、cron、agent.heartbeat否
工作階段與訊息session、messages否
工具與媒體tools、browser、skills、mcp、audio、talk否
UI 與其他ui、logging、identity、bindings否
Gateway 伺服器gateway.*（port、bind、auth、tailscale、TLS、HTTP）是
基礎架構discovery、plugins是
gateway.reload 和 gateway.remote 是例外 - 變更它們不會觸發重新啟動。

​
重新載入規劃

當你編輯透過 $include 參照的來源檔案時，OpenClaw 會從來源撰寫的版面規劃 重新載入，而不是從展平後的記憶體內視圖規劃。 這讓熱重載決策（熱套用或重新啟動）保持可預測，即使單一頂層區段 位於自己的 include 檔案中，例如 plugins: { $include: "./plugins.json5" }。如果來源版面不明確，重新載入規劃會保守失敗。

​
Config RPC（程式化更新）

對於透過 gateway API 寫入 config 的工具，建議使用此流程：
  • config.schema.lookup 用於檢查一個子樹（淺層 schema 節點 + 子項摘要）
  • config.get 用於擷取目前快照與 hash
  • config.patch 用於部分更新（JSON merge patch：物件合併、null 刪除、陣列取代）
  • 只有當你打算取代整個 config 時才使用 config.apply
  • update.run 用於明確自我更新並重新啟動；當重新啟動後的工作階段應執行一個後續回合時，請包含 continuationMessage
  • update.status 用於檢查最新的更新重新啟動 sentinel，並在重新啟動後驗證執行中的版本
Agent 應將 config.schema.lookup 視為取得精確欄位層級文件與限制的第一站。 當需要更廣泛的 config 對照表、預設值或專屬子系統參考連結時，請使用 Configuration reference。
控制平面寫入（config.apply、config.patch、update.run）會依 deviceId+clientIp 限制為每 60 秒 3 個請求。重新啟動請求會合併，接著在重新啟動週期之間強制執行 30 秒冷卻時間。 update.status 是唯讀的，但屬於 admin 範圍，因為重新啟動 sentinel 可能包含更新步驟摘要與命令輸出尾端。
部分 patch 範例： 
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。當 config 已存在時，兩個方法都需要 baseHash。

​
環境變數

OpenClaw 會從父程序加上下列來源讀取 env var：
  • 目前工作目錄中的 .env（如果存在）
  • ~/.openclaw/.env（全域 fallback）
這兩個檔案都不會覆寫既有 env var。你也可以在 config 中設定 inline env var： 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
如果啟用且預期的 key 尚未設定，OpenClaw 會執行你的登入 shell，並只匯入缺少的 key：
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
對應的 env var：OPENCLAW_LOAD_SHELL_ENV=1
使用 ${VAR_NAME} 在任何 config 字串值中參照 env var：
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
規則：
  • 只匹配大寫名稱：[A-Z_][A-Z0-9_]*
  • 缺少或空白的 var 會在載入時擲出錯誤
  • 使用 $${VAR} 逸出以輸出字面值
  • 可在 $include 檔案內運作
  • Inline 替換："${BASE}/v1" → "https://api.example.com/v1"
對於支援 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。

​
完整參考

如需完整逐欄位參考，請參閱 Configuration Reference。
相關：Configuration Examples · Configuration Reference · Doctor

​
相關