設定參考

• openclaw config schema 會列印用於驗證與 Control UI 的即時 JSON Schema，並合併內建/外掛/通道中繼資料。
• Agent 在編輯組態前，應呼叫 gateway 工具動作 config.schema.lookup，取得一個精確限定路徑範圍的 schema 節點。
• pnpm config:docs:check / pnpm config:docs:gen 會根據目前的 schema surface 驗證此文件的基準雜湊。

• 記憶體組態參考，涵蓋 agents.defaults.memorySearch.*、memory.qmd.*、memory.citations，以及 plugins.entries.memory-core.config.dreaming 下的夢境整理組態。
• 斜線命令，涵蓋目前內建 + 隨附的命令目錄。
• 通道特定命令 surface 請參閱所屬通道/外掛頁面。

​

通道

​

Agent 預設值、多 Agent、工作階段與訊息

• agents.defaults.*（工作區、模型、thinking、心跳偵測、記憶體、媒體、Skills、沙箱）
• multiAgent.*（多 Agent 路由與繫結）
• session.*（工作階段生命週期、壓縮、修剪）
• messages.*（訊息傳遞、TTS、Markdown 算繪）
• talk.*（Talk 模式）
  • talk.consultThinkingLevel：Control UI Talk 即時諮詢背後完整 OpenClaw Agent 執行的 thinking 等級覆寫
  • talk.consultFastMode：Control UI Talk 即時諮詢的一次性快速模式覆寫
  • talk.speechLocale：iOS/macOS 上 Talk 語音辨識的選用 BCP 47 語系 id
  • talk.silenceTimeoutMs：未設定時，Talk 會在送出轉錄文字前保留平台預設暫停視窗（macOS 和 Android 為 700 ms，iOS 為 900 ms）
  • talk.realtime.consultRouting：對於略過 openclaw_agent_consult 的已完成即時 Talk 轉錄文字，使用的閘道轉送備援

​

工具與自訂供應商

​

模型

{
  models: {
    // Optional. Default: true. Requires a Gateway restart when changed.
    pricing: { enabled: false },
  },
}

• models.mode：供應商目錄行為（merge 或 replace）。
• models.providers：以供應商 id 為鍵的自訂供應商對應表。
• models.providers.*.localService：本機模型伺服器的選用隨選程序管理器。OpenClaw 會探測已設定的健康端點，需要時啟動絕對路徑 command，等待就緒，然後送出模型請求。請參閱本機模型服務。
• models.pricing.enabled：控制在 sidecar 與通道到達閘道 ready 路徑後啟動的背景 pricing bootstrap。設為 false 時，閘道會略過 OpenRouter 與 LiteLLM pricing-catalog 擷取；已設定的 models.providers.*.models[].cost 值仍可用於本機成本估算。

​

MCP

{
  mcp: {
    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
    sessionIdleTtlMs: 600000,
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        timeout: 20,
        connectTimeout: 5,
        supportsParallelToolCalls: true,
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
        auth: "oauth",
        oauth: {
          scope: "docs.read",
        },
        sslVerify: true,
        clientCert: "/path/to/client.crt",
        clientKey: "/path/to/client.key",
        toolFilter: {
          include: ["search_*"],
          exclude: ["admin_*"],
        },
        // Optional Codex app-server projection controls.
        codex: {
          agents: ["main"],
          defaultToolsApprovalMode: "approve", // auto | prompt | approve
        },
      },
    },
  },
}

• mcp.servers：具名 stdio 或遠端 MCP 伺服器定義，供揭露已設定 MCP 工具的執行階段使用。 遠端項目使用 transport: "streamable-http" 或 transport: "sse"； type: "http" 是命令列介面原生別名，openclaw mcp set 與 openclaw doctor --fix 會將其正規化為標準 transport 欄位。
• mcp.servers.<name>.enabled：設為 false 可保留已儲存的伺服器定義，同時將其排除於嵌入式 OpenClaw MCP 探索與工具投射之外。
• mcp.servers.<name>.timeout / requestTimeoutMs：每個伺服器的 MCP 請求逾時，以秒或毫秒為單位。
• mcp.servers.<name>.connectTimeout / connectionTimeoutMs：每個伺服器的連線逾時，以秒或毫秒為單位。
• mcp.servers.<name>.supportsParallelToolCalls：選用的並行提示，供可選擇是否發出平行 MCP 工具呼叫的配接器使用。
• mcp.servers.<name>.auth：對需要 OAuth 的 HTTP MCP 伺服器設為 "oauth"。執行 openclaw mcp login <name> 可將 token 儲存在 OpenClaw 狀態下。
• mcp.servers.<name>.oauth：選用的 OAuth scope、重新導向 URL 與用戶端中繼資料 URL 覆寫。
• mcp.servers.<name>.sslVerify、clientCert、clientKey：私有端點與雙向 TLS 的 HTTP TLS 控制。
• mcp.servers.<name>.toolFilter：選用的每伺服器工具選取。include 會將探索到的 MCP 工具限制為相符名稱；exclude 會隱藏相符名稱。項目是精確的 MCP 工具名稱或簡單的 * glob。具有資源或提示的伺服器也會產生公用工具名稱（resources_list、resources_read、prompts_list、prompts_get），這些名稱也使用相同篩選器。
• mcp.servers.<name>.codex：選用的 Codex app-server 投射控制。 此區塊僅是 Codex app-server thread 的 OpenClaw 中繼資料；不影響 ACP 工作階段、一般 Codex harness 組態，或其他執行階段配接器。 非空的 codex.agents 會將伺服器限制為列出的 OpenClaw Agent id。 空白、空值或無效的限定範圍 Agent 清單，會被組態驗證拒絕，並由執行階段投射路徑省略，而不是變成全域。 codex.defaultToolsApprovalMode 會為該伺服器發出 Codex 原生的 default_tools_approval_mode。OpenClaw 會在將原生 mcp_servers 組態傳給 Codex 前移除 codex 區塊。省略此區塊可讓伺服器以 Codex 預設的 MCP 核准行為，投射給每個 Codex app-server Agent。
• mcp.sessionIdleTtlMs：工作階段範圍隨附 MCP 執行階段的閒置 TTL。 一次性嵌入式執行會要求執行結束清理；此 TTL 是長時間存在工作階段與未來呼叫者的後備機制。
• mcp.* 下的變更會透過處置快取的工作階段 MCP 執行階段熱套用。 下一次工具探索/使用會根據新組態重新建立它們，因此移除的 mcp.servers 項目會立即被清除，而不是等待閒置 TTL。
• 執行階段探索也會透過捨棄該工作階段的快取目錄，遵循 MCP 工具清單變更通知。宣告資源或提示的伺服器會取得用於列出/讀取資源與列出/擷取提示的公用工具。重複的工具呼叫失敗會暫停受影響的伺服器一小段時間，之後才會嘗試另一個呼叫。

​

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    workshop: {
      allowSymlinkTargetWrites: false,
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• allowBundled：僅針對隨附 Skills 的選用 allowlist（不影響受管理/工作區 Skills）。
• load.extraDirs：額外的共用 Skill 根目錄（最低優先順序）。
• load.allowSymlinkTargets：受信任的實際目標根目錄，當 Skill 符號連結位於其設定來源根目錄之外時，可解析到這些目標。
• workshop.allowSymlinkTargetWrites：允許 Skill Workshop apply 透過已受信任的符號連結目標寫入（預設：false）。
• install.preferBrew：為 true 時，在 brew 可用時優先使用 Homebrew 安裝器，之後才退回其他安裝器種類。
• install.nodeManager：metadata.openclaw.install 規格的 Node 安裝器偏好設定（npm | pnpm | yarn | bun）。
• install.allowUploadedArchives：允許受信任的 operator.admin 閘道用戶端，安裝透過 skills.upload.* 暫存的私有 zip 封存（預設：false）。這只會啟用已上傳封存路徑；一般 ClawHub 安裝不需要它。
• entries.<skillKey>.enabled: false 即使 Skill 已隨附/安裝，也會停用該 Skill。
• entries.<skillKey>.apiKey：給宣告主要環境變數之 Skills 的便利設定（明文字串或 SecretRef 物件）。
• limits.maxCandidatesPerRoot、limits.maxSkillsLoadedPerSource、limits.maxSkillsInPrompt、limits.maxSkillsPromptChars、limits.maxSkillFileBytes：限制 Skill 探索與面向模型的 Skills 提示。
• Skill Workshop 自主/核准設定（workshop.autonomous.enabled、workshop.approvalPolicy、workshop.maxPending、workshop.maxSkillBytes）記錄於 Skills 組態。

​

外掛

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-plugin"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

• 從 ~/.openclaw/extensions 和 <workspace>/.openclaw/extensions 下的套件或 bundle 目錄載入，以及從 plugins.load.paths 中列出的檔案或目錄載入。
• 將獨立外掛檔案放在 plugins.load.paths；自動探索的 extension 根目錄會忽略頂層 .js、.mjs 和 .ts 檔案，因此這些根目錄中的輔助指令碼不會阻擋啟動。
• 探索接受原生 OpenClaw 外掛，以及相容的 Codex bundles 和 Claude bundles，包括沒有 manifest 的 Claude 預設版面 bundle。
• 設定變更需要重新啟動閘道。
• allow：選用 allowlist（只載入列出的外掛）。deny 優先。
• plugins.entries.<id>.apiKey：外掛層級的 API key 便利欄位（當外掛支援時）。
• plugins.entries.<id>.env：外掛範圍的環境變數對應表。
• plugins.entries.<id>.hooks.allowPromptInjection：當為 false 時，core 會封鎖 before_prompt_build，並忽略舊版 before_agent_start 中會修改 prompt 的欄位，同時保留舊版 modelOverride 和 providerOverride。適用於原生外掛 hooks 和受支援的 bundle 提供 hook 目錄。
• plugins.entries.<id>.hooks.allowConversationAccess：當為 true 時，受信任的非 bundled 外掛可從 typed hooks 讀取原始對話內容，例如 llm_input、llm_output、before_model_resolve、before_agent_reply、before_agent_run、before_agent_finalize 和 agent_end。
• plugins.entries.<id>.subagent.allowModelOverride：明確信任此外掛可為背景 subagent runs 要求每次執行的 provider 和 model 覆寫。
• plugins.entries.<id>.subagent.allowedModels：受信任 subagent 覆寫可用的標準 provider/model 目標選用 allowlist。只有在你刻意要允許任何模型時才使用 "*"。
• plugins.entries.<id>.llm.allowModelOverride：明確信任此外掛可為 api.runtime.llm.complete 要求模型覆寫。
• plugins.entries.<id>.llm.allowedModels：受信任外掛 LLM completion 覆寫可用的標準 provider/model 目標選用 allowlist。只有在你刻意要允許任何模型時才使用 "*"。
• plugins.entries.<id>.llm.allowAgentIdOverride：明確信任此外掛可針對非預設 agent id 執行 api.runtime.llm.complete。
• plugins.entries.<id>.config：外掛定義的設定物件（可用時由原生 OpenClaw 外掛 schema 驗證）。
• 通道外掛帳號/runtime 設定位於 channels.<id> 下，並應由擁有該設定之外掛的 manifest channelConfigs metadata 描述，而不是由中央 OpenClaw 選項 registry 描述。

​

Codex harness 外掛設定

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_all_plugins: true,
            allow_destructive_actions: "auto",
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
                allow_destructive_actions: false,
              },
            },
          },
        },
      },
    },
  },
}

• plugins.entries.codex.config.codexPlugins.enabled：為 Codex harness 啟用原生 Codex 外掛/應用程式支援。預設值：false。
• plugins.entries.codex.config.codexPlugins.allow_all_plugins：在每個新的原生 Codex thread 中，公開目前可由已驗證 Codex 帳號存取的每個已連線應用程式。預設值：false。
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions： migrated 外掛應用程式 elicitations 的預設 destructive-action policy。 使用 true 可在不提示的情況下接受安全的 Codex approval schemas，使用 false 可拒絕它們，使用 "auto" 可將 Codex 所需 approvals 透過 OpenClaw 外掛 approvals 路由，或使用 "ask" 可針對每個外掛寫入/destructive action 提示，而不做 durable approval。"ask" 模式會清除受影響應用程式的 durable Codex per-tool approval overrides，並在 Codex thread 啟動前為該應用程式選取 human approvals reviewer。 預設值：true。
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled：當全域 codexPlugins.enabled 也為 true 時，啟用 migrated 外掛 entry。 明確 entries 的預設值：true。
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName： 穩定 marketplace identity。V1 只支援 "openai-curated"。
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName：來自 migration 的穩定 Codex 外掛 identity，例如 "google-calendar"。
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions： 個別外掛 destructive-action override。省略時會使用全域 allow_destructive_actions 值。個別外掛值接受相同的 true、false、"auto" 或 "ask" policies。

• plugins.entries.firecrawl.config.webFetch：Firecrawl web-fetch provider 設定。
  • apiKey：更高限制用的選用 Firecrawl API key（接受 SecretRef）。會 fallback 到 plugins.entries.firecrawl.config.webSearch.apiKey、舊版 tools.web.fetch.firecrawl.apiKey 或 FIRECRAWL_API_KEY 環境變數。
  • baseUrl：Firecrawl API base URL（預設：https://api.firecrawl.dev；self-hosted overrides 必須指向 private/internal endpoints）。
  • onlyMainContent：只從頁面擷取主要內容（預設：true）。
  • maxAgeMs：最大快取時間，單位為毫秒（預設：172800000 / 2 天）。
  • timeoutSeconds：scrape request timeout，單位為秒（預設：60）。
• plugins.entries.xai.config.xSearch：xAI X Search（Grok web search）設定。
  • enabled：啟用 X Search provider。
  • model：用於搜尋的 Grok 模型（例如 "grok-4-1-fast"）。
• plugins.entries.memory-core.config.dreaming：memory 夢境整理設定。階段和 thresholds 請參閱 夢境整理。
  • enabled：master 夢境整理開關（預設 false）。
  • frequency：每次完整夢境整理 sweep 的 cron cadence（預設為 "0 3 * * *"）。
  • model：選用 Dream Diary subagent 模型覆寫。需要 plugins.entries.memory-core.subagent.allowModelOverride: true；搭配 allowedModels 以限制目標。Model-unavailable errors 會使用 session 預設模型重試一次；trust 或 allowlist failures 不會靜默 fallback。
  • phase policy 和 thresholds 是實作細節（不是 user-facing config keys）。
• 完整 memory 設定位於 Memory configuration reference：
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• 已啟用的 Claude bundle 外掛也可以從 settings.json 貢獻 embedded OpenClaw defaults；OpenClaw 會將它們套用為 sanitized agent settings，而不是 raw OpenClaw config patches。
• plugins.slots.memory：選擇 active memory 外掛 id，或使用 "none" 停用 memory 外掛。
• plugins.slots.contextEngine：選擇 active context engine 外掛 id；除非你安裝並選取另一個 engine，否則預設為 "legacy"。

​

Commitments

• commitments.enabled：為推斷出的 follow-up commitments 啟用隱藏 LLM extraction、storage 和心跳偵測 delivery。預設值：false。
• commitments.maxPerDay：每個 agent session 在 rolling day 中傳遞的推斷 follow-up commitments 最大數量。預設值：3。

​

瀏覽器

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    tabCleanup: {
      enabled: true,
      idleMinutes: 120,
      maxTabsPerSession: 8,
      sweepMinutes: 5,
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

• evaluateEnabled: false 會停用 act:evaluate 和 wait --fn。
• tabCleanup 會在閒置一段時間後，或當工作階段超過其上限時，回收已追蹤的主要代理分頁。設定 idleMinutes: 0 或 maxTabsPerSession: 0 可停用這些個別清理模式。
• ssrfPolicy.dangerouslyAllowPrivateNetwork 未設定時會停用，因此瀏覽器導覽預設會保持嚴格。
• 只有在你有意信任私有網路瀏覽器導覽時，才設定 ssrfPolicy.dangerouslyAllowPrivateNetwork: true。
• 在嚴格模式下，遠端 CDP 設定檔端點（profiles.*.cdpUrl）在可達性/探索檢查期間也會受到相同的私有網路封鎖。
• ssrfPolicy.allowPrivateNetwork 仍支援作為舊版別名。
• 在嚴格模式下，使用 ssrfPolicy.hostnameAllowlist 和 ssrfPolicy.allowedHostnames 設定明確例外。
• 遠端設定檔僅可附加（停用啟動/停止/重設）。
• profiles.*.cdpUrl 接受 http://、https://、ws:// 和 wss://。 當你希望 OpenClaw 探索 /json/version 時，請使用 HTTP(S)；當你的供應商提供直接的 DevTools WebSocket URL 時，請使用 WS(S)。
• remoteCdpTimeoutMs 和 remoteCdpHandshakeTimeoutMs 會套用於遠端和 attachOnly CDP 可達性，以及開啟分頁的請求。受管理的 loopback 設定檔會保留本機 CDP 預設值。持續性遠端 Playwright 分頁列舉會使用較大的值作為其操作期限。
• 如果外部管理的 CDP 服務可透過 loopback 存取，請將該設定檔的 attachOnly: true；否則 OpenClaw 會將該 loopback 連接埠視為本機受管理的瀏覽器設定檔，並可能回報本機連接埠擁有權錯誤。
• existing-session 設定檔使用 Chrome MCP 而非 CDP，並可附加到所選主機或透過已連線的瀏覽器節點附加。
• existing-session 設定檔可設定 userDataDir，以指定特定的 Chromium 系瀏覽器設定檔，例如 Brave 或 Edge。
• 當 Chrome 已在 DevTools HTTP(S) 探索端點或直接 WS(S) 端點後方執行時，existing-session 設定檔可設定 cdpUrl。在該模式下，OpenClaw 會將端點傳遞給 Chrome MCP，而不是使用自動連線；Chrome MCP 啟動引數會忽略 userDataDir。
• existing-session 設定檔會保留目前的 Chrome MCP 路由限制：使用快照/ref 驅動的動作，而不是 CSS 選擇器目標定位、單一檔案上傳掛鉤、無對話方塊逾時覆寫、無 wait --load networkidle，以及無 responsebody、PDF 匯出、下載攔截或批次動作。
• 本機受管理的 openclaw 設定檔會自動指派 cdpPort 和 cdpUrl；只有遠端 CDP 設定檔或 existing-session 端點附加時，才明確設定 cdpUrl。
• 本機受管理的設定檔可設定 executablePath，以覆寫該設定檔的全域 browser.executablePath。使用此設定可讓一個設定檔在 Chrome 中執行，另一個在 Brave 中執行。
• 本機受管理的設定檔會在程序啟動後，使用 browser.localLaunchTimeoutMs 進行 Chrome CDP HTTP 探索，並使用 browser.localCdpReadyTimeoutMs 等待啟動後的 CDP websocket 就緒。在較慢的主機上，如果 Chrome 可成功啟動但就緒檢查與啟動流程競爭，請提高這些值。兩個值都必須是最高 120000 ms 的正整數；無效的設定值會遭拒。
• 自動偵測順序：預設瀏覽器（如果是 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
• browser.executablePath 和 browser.profiles.<name>.executablePath 都接受 ~ 和 ~/...，代表你的作業系統家目錄，並會在 Chromium 啟動前展開。existing-session 設定檔上的每個設定檔 userDataDir 也會展開波浪號。
• 控制服務：僅限 loopback（連接埠衍生自 gateway.port，預設為 18791）。
• extraArgs 會將額外啟動旗標附加到本機 Chromium 啟動流程（例如 --disable-gpu、視窗大小或偵錯旗標）。

​

使用者介面

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

• seamColor：原生應用程式使用者介面外框的強調色（Talk Mode 氣泡色調等）。
• assistant：Control UI 身分覆寫。會退回使用作用中的代理身分。

​

閘道

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
      // chatMessageMaxWidth: "min(1280px, 82%)", // optional grouped chat message max-width
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    terminal: {
      enabled: false,
      // shell: "/bin/zsh",
    },
    remote: {
      url: "ws://127.0.0.1:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    nodes: {
      pairing: {
        // Optional. Default unset/disabled.
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
      allowCommands: ["canvas.navigate"],
      denyCommands: ["system.run"],
    },
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list for owner/admin callers
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

​

OpenAI 相容端點

• 管理員 HTTP RPC：預設關閉，作為 admin-http-rpc 外掛。啟用此外掛以註冊 POST /api/v1/admin/rpc。請參閱管理員 HTTP RPC。
• Chat Completions：預設停用。使用 gateway.http.endpoints.chatCompletions.enabled: true 啟用。
• Responses API：gateway.http.endpoints.responses.enabled。
• Responses URL 輸入強化：
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist 空允許清單會視為未設定；使用 gateway.http.endpoints.responses.files.allowUrl=false 和/或 gateway.http.endpoints.responses.images.allowUrl=false 停用 URL 擷取。
• 選用回應強化標頭：
  • gateway.http.securityHeaders.strictTransportSecurity（僅針對你控制的 HTTPS 來源設定；請參閱受信任代理驗證）

​

多執行個體隔離

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

​

gateway.tls

{
  gateway: {
    tls: {
      enabled: false,
      autoGenerate: false,
      certPath: "/etc/openclaw/tls/server.crt",
      keyPath: "/etc/openclaw/tls/server.key",
      caPath: "/etc/openclaw/tls/ca-bundle.crt",
    },
  },
}

• enabled：在閘道監聽器啟用 TLS 終止（HTTPS/WSS）（預設：false）。
• autoGenerate：未設定明確檔案時，自動產生本機自簽憑證/金鑰組；僅供本機/開發使用。
• certPath：TLS 憑證檔案的檔案系統路徑。
• keyPath：TLS 私密金鑰檔案的檔案系統路徑；請限制權限。
• caPath：用於用戶端驗證或自訂信任鏈的選用 CA 套件路徑。

​

gateway.reload

{
  gateway: {
    reload: {
      mode: "hybrid", // off | restart | hot | hybrid
      debounceMs: 500,
      deferralTimeoutMs: 300000,
    },
  },
}

• mode：控制執行階段如何套用設定編輯。
  • "off"：忽略即時編輯；變更需要明確重新啟動。
  • "restart"：設定變更時一律重新啟動閘道程序。
  • "hot"：不重新啟動，直接在程序內套用變更。
  • "hybrid"（預設）：先嘗試熱重新載入；必要時退回重新啟動。
• debounceMs：套用設定變更前的去抖時間窗，單位為毫秒（非負整數；預設：300）。
• deferralTimeoutMs：在強制重新啟動或通道熱重新載入前，等待執行中作業的選用最長時間，單位為毫秒。省略時使用預設的有界等待（300000）；設為 0 會無限期等待，並定期記錄仍在等待的警告。

​

鉤子

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.4-mini",
      },
    ],
  },
}

• hooks.enabled=true 需要非空的 hooks.token。
• hooks.token 應與作用中的閘道共享密鑰驗證（gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD）不同；啟動時若偵測到重複使用，會記錄非致命的安全警告。
• openclaw security audit 會將鉤子/閘道驗證重複使用標記為嚴重發現，包括只在稽核時提供的閘道密碼驗證（--auth password --password <password>）。執行 openclaw doctor --fix 以輪替已持久保存且重複使用的 hooks.token，然後更新外部鉤子傳送端以使用新的鉤子權杖。
• hooks.path 不能是 /；請使用專用子路徑，例如 /hooks。
• 如果 hooks.allowRequestSessionKey=true，請限制 hooks.allowedSessionKeyPrefixes（例如 ["hook:"]）。
• 如果對應或預設集使用樣板化的 sessionKey，請設定 hooks.allowedSessionKeyPrefixes 和 hooks.allowRequestSessionKey=true。靜態對應鍵不需要該選擇加入。

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • 只有在 hooks.allowRequestSessionKey=true 時，才接受來自請求承載的 sessionKey（預設：false）。
• POST /hooks/<name> → 透過 hooks.mappings 解析
  • 樣板渲染的對應 sessionKey 值會視為外部提供，也需要 hooks.allowRequestSessionKey=true。

​

Gmail 整合

• 內建 Gmail 預設集使用 sessionKey: "hook:gmail:{{messages[0].id}}"。
• 如果保留該逐訊息路由，請設定 hooks.allowRequestSessionKey: true，並限制 hooks.allowedSessionKeyPrefixes 以符合 Gmail 命名空間，例如 ["hook:", "hook:gmail:"]。
• 如果需要 hooks.allowRequestSessionKey: false，請使用靜態 sessionKey 覆寫預設集，而不是使用樣板化預設值。

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

• 設定後，閘道會在啟動時自動啟動 gog gmail watch serve。設定 OPENCLAW_SKIP_GMAIL_WATCHER=1 可停用。
• 不要在閘道旁另外執行 gog gmail watch serve。

​

Canvas 外掛主機

{
  plugins: {
    entries: {
      canvas: {
        config: {
          host: {
            root: "~/.openclaw/workspace/canvas",
            liveReload: true,
            // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
          },
        },
      },
    },
  },
}

• 透過閘道連接埠，在 HTTP 下提供代理可編輯的 HTML/CSS/JS 和 A2UI：
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• 僅限本機：保持 gateway.bind: "loopback"（預設）。
• 非 loopback 繫結：Canvas 路由需要閘道驗證（權杖/密碼/受信任代理），與其他閘道 HTTP 介面相同。
• 節點 WebView 通常不會傳送驗證標頭；節點配對並連線後，閘道會公告節點範圍的能力 URL，以供 Canvas/A2UI 存取。
• 能力 URL 會繫結到作用中的節點 WS 工作階段，且很快過期。不使用以 IP 為基礎的備援。
• 將即時重新載入用戶端注入到提供的 HTML。
• 空白時自動建立起始 index.html。
• 也會在 /__openclaw__/a2ui/ 提供 A2UI。
• 變更需要重新啟動閘道。
• 對大型目錄或 EMFILE 錯誤，請停用即時重新載入。

​

探索

​

mDNS (Bonjour)

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• minimal（預設）：從 TXT 記錄省略 cliPath + sshPort。
• full：包含 cliPath + sshPort；區域網路多播公告仍需要啟用隨附的 bonjour 外掛。
• off：在不變更外掛啟用狀態的情況下，抑制區域網路多播公告。
• 隨附的 bonjour 外掛會在 macOS 主機上自動啟動，在 Linux、Windows 和容器化閘道部署中則為選用。
• 當系統主機名稱是有效的 DNS 標籤時，主機名稱預設為系統主機名稱，否則會退回到 openclaw。可使用 OPENCLAW_MDNS_HOSTNAME 覆寫。
• OPENCLAW_DISABLE_BONJOUR=1 會完全停用 mDNS 公告，並覆寫 discovery.mdns.mode。

​

廣域 (DNS-SD)

{
  discovery: {
    wideArea: { enabled: true },
  },
}

​

環境

​

env（內嵌環境變數）

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• 只有在處理程序環境缺少該鍵時，才會套用內嵌環境變數。
• .env 檔案：CWD .env + ~/.openclaw/.env（兩者都不會覆寫現有變數）。
• shellEnv：從你的登入 shell 設定檔匯入缺少的預期鍵。
• 請參閱環境以了解完整優先順序。

​

環境變數替換

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

• 只會比對大寫名稱：[A-Z_][A-Z0-9_]*。
• 缺少或空白的變數會在載入設定時擲出錯誤。
• 使用 $${VAR} 跳脫以取得字面值 ${VAR}。
• 可與 $include 搭配使用。

​

密鑰

​

SecretRef

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

• provider 模式：^[a-z][a-z0-9_-]{0,63}$
• source: "env" id 模式：^[A-Z][A-Z0-9_]{0,127}$
• source: "file" id：絕對 JSON 指標（例如 "/providers/openai/apiKey"）
• source: "exec" id 模式：^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$（支援 AWS 風格的 secret#json_key 選擇器）
• source: "exec" id 不得包含 . 或 .. 的斜線分隔路徑片段（例如 a/../b 會被拒絕）

​

支援的憑證介面

• 標準矩陣：SecretRef 憑證介面
• secrets apply 以支援的 openclaw.json 憑證路徑為目標。
• auth-profiles.json 參照包含在執行階段解析與稽核涵蓋範圍中。

​

密鑰提供者設定

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

• file 提供者支援 mode: "json" 與 mode: "singleValue"（在 singleValue 模式中，id 必須是 "value"）。
• 當 Windows ACL 驗證無法使用時，檔案與 exec 提供者路徑會以失敗關閉處理。只對無法驗證的受信任路徑設定 allowInsecurePath: true。
• exec 提供者需要絕對 command 路徑，並在 stdin/stdout 上使用通訊協定酬載。
• 預設會拒絕符號連結命令路徑。設定 allowSymlinkCommand: true 可允許符號連結路徑，同時驗證解析後的目標路徑。
• 如果已設定 trustedDirs，受信任目錄檢查會套用到解析後的目標路徑。
• exec 子環境預設為最小化；請用 passEnv 明確傳遞必要變數。
• Secret 參照會在啟用時解析成記憶體內快照，之後請求路徑只讀取該快照。
• 啟用期間會套用作用中介面篩選：已啟用介面上的未解析參照會使啟動/重新載入失敗，而非作用中介面會略過並附上診斷資訊。

​

驗證儲存

{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:personal": { provider: "openai", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      openai: ["openai:personal"],
    },
  },
}

• 每個 agent 的設定檔會儲存在 <agentDir>/auth-profiles.json。
• auth-profiles.json 支援靜態憑證模式的值層級參照（api_key 使用 keyRef，token 使用 tokenRef）。
• 舊版扁平 auth-profiles.json 對應，例如 { "provider": { "apiKey": "..." } }，不是執行階段格式；openclaw doctor --fix 會將它們重寫為標準 provider:default API key 設定檔，並建立 .legacy-flat.*.bak 備份。
• OAuth 模式設定檔（auth.profiles.<id>.mode = "oauth"）不支援由 SecretRef 支援的驗證設定檔憑證。
• 靜態執行階段憑證來自記憶體內已解析快照；發現舊版靜態 auth.json 項目時會將其清除。
• 舊版 OAuth 會從 ~/.openclaw/credentials/oauth.json 匯入。
• 請參閱 OAuth。
• Secrets 執行階段行為與 audit/configure/apply 工具：Secrets 管理。

​

auth.cooldowns

{
  auth: {
    cooldowns: {
      billingBackoffHours: 5,
      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
      billingMaxHours: 24,
      authPermanentBackoffMinutes: 10,
      authPermanentMaxMinutes: 60,
      failureWindowHours: 24,
      overloadedProfileRotations: 1,
      overloadedBackoffMs: 0,
      rateLimitedProfileRotations: 1,
    },
  },
}

• billingBackoffHours：當設定檔因真正的帳務/點數不足錯誤而失敗時，以小時為單位的基礎退避（預設：5）。即使在 401/403 回應上，明確的帳務文字仍可歸入此處，但提供者特定文字比對器會維持限定於擁有它們的提供者（例如 OpenRouter 的 Key limit exceeded）。可重試的 HTTP 402 使用量時段或組織/工作區支出限制訊息，則會留在 rate_limit 路徑。
• billingBackoffHoursByProvider：選用的每提供者帳務退避小時覆寫。
• billingMaxHours：帳務退避指數成長的小時上限（預設：24）。
• authPermanentBackoffMinutes：高信心 auth_permanent 失敗的基礎退避分鐘數（預設：10）。
• authPermanentMaxMinutes：auth_permanent 退避成長的分鐘上限（預設：60）。
• failureWindowHours：用於退避計數器的滾動時窗小時數（預設：24）。
• overloadedProfileRotations：切換到模型備援前，針對過載錯誤進行同提供者驗證設定檔輪替的最大次數（預設：1）。例如 ModelNotReadyException 這類提供者忙碌形態會歸入此處。
• overloadedBackoffMs：重試過載提供者/設定檔輪替前的固定延遲（預設：0）。
• rateLimitedProfileRotations：切換到模型備援前，針對速率限制錯誤進行同提供者驗證設定檔輪替的最大次數（預設：1）。該速率限制桶包含提供者形態文字，例如 Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded 與 resource exhausted。

​

稽核

{
  audit: {
    enabled: true,
  },
}

• enabled：記錄新的稽核事件（預設：true）。帳本預設開啟，因為只在事件發生後才啟用的稽核軌跡無法解釋該事件。設定為 false 會立即停止新寫入；現有記錄在過期前仍可讀取。重新開啟後會從該時間點繼續記錄；中間缺口不會回填。

​

記錄

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

• 預設記錄檔：/tmp/openclaw/openclaw-YYYY-MM-DD.log。
• 設定 logging.file 可使用穩定路徑。
• 使用 --verbose 時，consoleLevel 會提升為 debug。
• maxFileBytes：輪替前作用中記錄檔大小上限，以位元組為單位（正整數；預設：104857600 = 100 MB）。OpenClaw 會在作用中文件旁保留最多五個編號封存檔。
• redactSensitive / redactPatterns：針對主控台輸出、檔案記錄、OTLP 記錄項目與持久化工作階段逐字稿文字的盡力遮罩。redactSensitive: "off" 只停用這項一般記錄/逐字稿政策；UI/工具/診斷安全介面仍會在發出前遮蔽秘密。

​

診斷

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,
    stuckSessionAbortMs: 300000,
    memoryPressureSnapshot: false,

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      tracesEndpoint: "https://traces.example.com/v1/traces",
      metricsEndpoint: "https://metrics.example.com/v1/metrics",
      logsEndpoint: "https://logs.example.com/v1/logs",
      protocol: "http/protobuf", // http/protobuf | grpc
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      logsExporter: "otlp",
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
        toolDefinitions: false,
      },
    },

    cacheTrace: {
      enabled: false,
      filePath: "~/.openclaw/logs/cache-trace.jsonl",
      includeMessages: true,
      includePrompt: true,
      includeSystem: true,
    },
  },
}

• enabled：檢測輸出的主切換（預設：true）。
• flags：啟用目標記錄輸出的旗標字串陣列（支援 "telegram.*" 或 "*" 這類萬用字元）。
• stuckSessionWarnMs：無進度時間門檻，以毫秒為單位，用於將長時間執行的處理工作階段分類為 session.long_running、session.stalled 或 session.stuck（預設：120000）。回覆、工具、狀態、區塊與 ACP 進度會重設計時器；重複的 session.stuck 診斷在未變更時會退避。
• stuckSessionAbortMs：符合資格的停滯中作用中工作可被中止排空以復原前的無進度時間門檻，以毫秒為單位。未設定時，OpenClaw 會使用較安全的延長嵌入式執行視窗，至少為 5 分鐘且為 stuckSessionWarnMs 的 3 倍。
• memoryPressureSnapshot：當記憶體壓力達到 critical 時，擷取已遮蔽的 OOM 前穩定性快照（預設：false）。設定為 true 可在保留一般記憶體壓力事件的同時，加入穩定性套件檔案掃描/寫入。
• otel.enabled：啟用 OpenTelemetry 匯出管線（預設：false）。完整設定、訊號目錄與隱私模型，請參閱 OpenTelemetry 匯出。
• otel.endpoint：OTel 匯出的收集器 URL。
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint：選用的訊號特定 OTLP 端點。設定後，它們只會覆寫該訊號的 otel.endpoint。
• otel.protocol："http/protobuf"（預設）或 "grpc"。
• otel.headers：隨 OTel 匯出請求傳送的額外 HTTP/gRPC 中繼資料標頭。
• otel.serviceName：資源屬性的服務名稱。
• otel.traces / otel.metrics / otel.logs：啟用追蹤、指標或記錄匯出。
• otel.logsExporter：記錄匯出接收端："otlp"（預設）、每 stdout 行一個 JSON 物件的 "stdout"，或 "both"。
• otel.sampleRate：追蹤取樣率 0-1。
• otel.flushIntervalMs：定期遙測排清間隔，以毫秒為單位。
• otel.captureContent：選擇加入 OTEL span 屬性的原始內容擷取。預設為關閉。布林值 true 會擷取非系統訊息/工具內容；物件形式可讓你明確啟用 inputMessages、outputMessages、toolInputs、toolOutputs、systemPrompt 與 toolDefinitions。
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental：最新實驗性 GenAI 推論 span 形態的環境切換，包含 {gen_ai.operation.name} {gen_ai.request.model} span 名稱、CLIENT span kind，以及用 gen_ai.provider.name 取代舊版 gen_ai.system。預設 span 會保留 openclaw.model.call 與 gen_ai.system 以維持相容性；GenAI 指標使用有界語意屬性。
• OPENCLAW_OTEL_PRELOADED=1：用於已註冊全域 OpenTelemetry SDK 主機的環境切換。OpenClaw 隨後會略過外掛擁有的 SDK 啟動/關閉，同時保持診斷監聽器作用中。
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT、OTEL_EXPORTER_OTLP_METRICS_ENDPOINT 與 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT：當相符設定鍵未設定時使用的訊號特定端點環境變數。
• cacheTrace.enabled：記錄嵌入式執行的快取追蹤快照（預設：false）。
• cacheTrace.filePath：快取追蹤 JSONL 的輸出路徑（預設：$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl）。
• cacheTrace.includeMessages / includePrompt / includeSystem：控制快取追蹤輸出中包含的內容（全都預設為 true）。

​

更新

{
  update: {
    channel: "stable", // stable | extended-stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

• channel：發行通道 - "stable"、"extended-stable"、"beta" 或 "dev"。Extended-stable 是僅套件、前景/按需通道；啟動檢查與背景自動更新會略過它。
• checkOnStart：閘道啟動時檢查 npm 更新（預設：true）。
• auto.enabled：為套件安裝啟用背景自動更新（預設：false）。
• auto.stableDelayHours：穩定通道自動套用前的最短延遲小時數（預設：6；最大：168）。
• auto.stableJitterHours：額外的穩定通道推出分散視窗小時數（預設：12；最大：168）。
• auto.betaCheckIntervalHours：beta 通道檢查執行頻率，以小時為單位（預設：1；最大：24）。

​

ACP

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    fallbacks: ["acpx-secondary"],
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    maxConcurrentSessions: 10,

    stream: {
      coalesceIdleMs: 50,
      maxChunkChars: 1000,
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
      maxOutputChars: 50000,
      maxSessionUpdateChars: 500,
    },

    runtime: {
      ttlMinutes: 30,
    },
  },
}

• enabled：全域 ACP 功能閘門（預設：true；設為 false 可隱藏 ACP 分派與衍生操作入口）。
• dispatch.enabled：ACP 工作階段回合分派的獨立閘門（預設：true）。設為 false 可保留 ACP 命令可用，同時封鎖執行。
• backend：預設 ACP 執行階段後端 ID（必須符合已註冊的 ACP 執行階段外掛）。 請先安裝後端外掛；如果已設定 plugins.allow，請包含後端外掛 ID（例如 acpx），否則 ACP 後端將不會載入。
• fallbacks：當主要後端在產生任何輸出前，因看似暫時性的錯誤（不可用、受速率限制、配額用盡或過載）提早失敗時，依序嘗試的備援 ACP 後端 ID 清單。每個項目都必須符合已註冊的 ACP 執行階段外掛後端。
• defaultAgent：當衍生未指定明確目標時使用的備援 ACP 目標代理 ID。
• allowedAgents：允許用於 ACP 執行階段工作階段的代理 ID 允許清單；空白表示沒有額外限制。
• maxConcurrentSessions：同時作用中的 ACP 工作階段數上限。
• stream.coalesceIdleMs：串流文字的閒置清空視窗，以毫秒為單位。
• stream.maxChunkChars：拆分串流區塊投影前的最大區塊大小。
• stream.repeatSuppression：每個回合抑制重複的狀態/工具行（預設：true）。
• stream.deliveryMode："live" 會逐步串流；"final_only" 會緩衝到回合終止事件。
• stream.hiddenBoundarySeparator：隱藏工具事件後、可見文字前的分隔符（預設："paragraph"）。
• stream.maxOutputChars：每個 ACP 回合投影的助理輸出字元數上限。
• stream.maxSessionUpdateChars：投影 ACP 狀態/更新行的最大字元數。
• stream.tagVisibility：標籤名稱到布林可見性覆寫的記錄，用於串流事件。
• runtime.ttlMinutes：ACP 工作階段工作程序在符合清理資格前的閒置 TTL，以分鐘為單位。
• runtime.installCommand：啟動 ACP 執行階段環境時可執行的選用安裝命令。

​

命令列介面

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• cli.banner.taglineMode 控制橫幅標語樣式：
  • "random"（預設）：輪替的趣味/季節性標語。
  • "default"：固定中性標語（All your chats, one OpenClaw.）。
  • "off"：不顯示標語文字（仍會顯示橫幅標題/版本）。
• 若要隱藏整個橫幅（不只是標語），請設定環境變數 OPENCLAW_HIDE_BANNER=1。

​

設定精靈

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
    securityAcknowledgedAt: "2026-01-01T00:00:00.000Z",
  },
}

​

身分

​

橋接（舊版，已移除）

{
  "bridge": {
    "enabled": true,
    "port": 18790,
    "bind": "tailnet",
    "tls": {
      "enabled": true,
      "autoGenerate": true
    }
  }
}

​

排程

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}

• sessionRetention：在從 sessions.json 修剪已完成的隔離排程執行工作階段前，要保留多久。也會控制已封存且已刪除的排程記錄稿清理。預設：24h；設為 false 可停用。
• runLog.maxBytes：為了與較舊的檔案式排程執行記錄相容而接受。預設：2_000_000 位元組。
• runLog.keepLines：每個工作保留的最新 SQLite 執行歷程列數。預設：2000。
• webhookToken：用於排程網路鉤子 POST 傳遞（delivery.mode = "webhook"）的 bearer token；若省略，則不會傳送 auth 標頭。
• webhook：已淘汰的舊版備援網路鉤子 URL（http/https），供 openclaw doctor --fix 用來遷移仍含有 notify: true 的已儲存工作；執行階段傳遞會使用每個工作的 delivery.mode="webhook" 加上 delivery.to，或在保留公告傳遞時使用 delivery.completionDestination。

​

cron.retry

{
  cron: {
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
    },
  },
}

• maxAttempts：Cron 作業在暫時性錯誤時的最大重試次數（預設：3；範圍：0-10）。
• backoffMs：每次重試嘗試的退避延遲陣列，單位為 ms（預設：[30000, 60000, 300000]；1-10 個項目）。
• retryOn：會觸發重試的錯誤類型 - "rate_limit"、"overloaded"、"network"、"timeout"、"server_error"。省略時會重試所有暫時性類型。

​

cron.failureAlert

{
  cron: {
    failureAlert: {
      enabled: false,
      after: 3,
      cooldownMs: 3600000,
      includeSkipped: false,
      mode: "announce",
      accountId: "main",
    },
  },
}

• enabled：啟用 Cron 作業失敗警示（預設：false）。
• after：警示觸發前的連續失敗次數（正整數，最小值：1）。
• cooldownMs：同一作業重複警示之間的最小毫秒數（非負整數）。
• includeSkipped：將連續略過的執行計入警示門檻（預設：false）。略過的執行會分開追蹤，且不會影響執行錯誤退避。
• mode：傳送模式 - "announce" 透過頻道訊息傳送；"webhook" 發布至已設定的網路鉤子。
• accountId：選用的帳號或頻道 id，用於限定警示傳送範圍。

​

cron.failureDestination

{
  cron: {
    failureDestination: {
      mode: "announce",
      channel: "last",
      to: "channel:C1234567890",
      accountId: "main",
    },
  },
}

• 所有作業 Cron 失敗通知的預設目的地。
• mode："announce" 或 "webhook"；當有足夠目標資料時，預設為 "announce"。
• channel：公告傳送的頻道覆寫。"last" 會重用最後已知的傳送頻道。
• to：明確的公告目標或網路鉤子 URL。網路鉤子模式必填。
• accountId：選用的傳送帳號覆寫。
• 每個作業的 delivery.failureDestination 會覆寫此全域預設值。
• 當未設定全域或每個作業的失敗目的地時，已透過 announce 傳送的作業，會在失敗時退回使用該主要公告目標。
• delivery.failureDestination 僅支援 sessionTarget="isolated" 作業，除非該作業的主要 delivery.mode 是 "webhook"。

​

媒體模型範本變數

​

設定包含項目（$include）

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

• 單一檔案：取代包含它的物件。
• 檔案陣列：依序深度合併（後面的會覆寫前面的）。
• 同層鍵：在包含項目之後合併（覆寫包含的值）。
• 巢狀包含項目：最多 10 層深。
• 路徑：相對於包含它的檔案解析，但必須保留在頂層設定目錄（openclaw.json 的 dirname）內。絕對/../ 形式只有在仍解析到該邊界內時才允許。設定 OPENCLAW_INCLUDE_ROOTS（絕對路徑）可允許設定目錄外的其他根目錄。
• 限制：路徑不得包含 null 位元組，且在解析前後都必須嚴格短於 4096 個字元；每個被包含的檔案上限為 2 MB。
• OpenClaw 擁有的寫入若只變更由單一檔案包含支援的一個頂層區段，會寫入該被包含的檔案。例如，plugins install 會在 plugins.json5 中更新 plugins: { $include: "./plugins.json5" }，並讓 openclaw.json 保持不變。
• 根包含項目、包含陣列，以及帶有同層覆寫的包含項目，對 OpenClaw 擁有的寫入而言為唯讀；這些寫入會失敗關閉，而不是攤平設定。
• 錯誤：針對遺失檔案、剖析錯誤、循環包含、無效路徑格式，以及長度過長提供清楚訊息。

​

相關

• 設定
• 設定範例
• Doctor