設定 — 代理

agents.*、multiAgent.*、session.*、messages.* 和 talk.* 底下的代理範圍設定鍵。關於頻道、工具、Gateway 執行階段，以及其他頂層鍵，請參閱設定參考。

代理預設值

agents.defaults.workspace

預設值：~/.openclaw/workspace。

{  agents: { defaults: { workspace: "~/.openclaw/workspace" } },}

agents.defaults.repoRoot

顯示於系統提示 Runtime 行的可選儲存庫根目錄。如果未設定，OpenClaw 會從工作區開始向上遍歷來自動偵測。

{  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },}

agents.defaults.skills

可選的代理預設 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，預設即不限制 Skills。
• 省略 agents.list[].skills 以繼承預設值。
• 設定 agents.list[].skills: [] 表示沒有 Skills。
• 非空的 agents.list[].skills 清單是該代理的最終集合；它 不會與預設值合併。

agents.defaults.skipBootstrap

停用工作區啟動檔案（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md）的自動建立。

{  agents: { defaults: { skipBootstrap: true } },}

agents.defaults.skipOptionalBootstrapFiles

略過所選可選工作區檔案的建立，同時仍寫入必要的啟動檔案。有效值：SOUL.md、USER.md、HEARTBEAT.md 和 IDENTITY.md。

{  agents: {    defaults: {      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],    },  },}

agents.defaults.contextInjection

控制工作區啟動檔案何時注入系統提示。預設值："always"。

• "continuation-skip"：安全的延續回合（已完成的助理回應之後）會略過工作區啟動內容的重新注入，以減少提示大小。Heartbeat 執行與 Compaction 後重試仍會重建內容。
• "never"：在每個回合停用工作區啟動與內容檔案注入。僅針對完全自行掌控提示生命週期的代理使用此選項（自訂內容引擎、會建構自身內容的原生執行階段，或不需要啟動檔案的專用工作流程）。Heartbeat 與 Compaction 復原回合也會略過注入。

{  agents: { defaults: { contextInjection: "continuation-skip" } },}

agents.defaults.bootstrapMaxChars

截斷前每個工作區啟動檔案的最大字元數。預設值：12000。

{  agents: { defaults: { bootstrapMaxChars: 12000 } },}

agents.defaults.bootstrapTotalMaxChars

所有工作區啟動檔案合計注入的最大總字元數。預設值：60000。

{  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },}

agents.defaults.bootstrapPromptTruncationWarning

控制啟動內容遭截斷時，代理可見的系統提示通知。 預設值："once"。

• "off"：絕不將截斷通知文字注入系統提示。
• "once"：針對每個唯一的截斷簽名注入一次簡潔通知（建議）。
• "always"：只要存在截斷，就在每次執行時注入簡潔通知。

詳細的原始/注入計數與設定調校欄位會保留在診斷資料中， 例如內容/狀態報告與記錄；例行的 WebChat 使用者/執行階段內容只會 取得簡潔的復原通知。

{  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always}

內容預算歸屬對照

OpenClaw 有多個高容量提示/內容預算，且它們刻意依子系統拆分， 而不是全部流經同一個通用旋鈕。

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars： 一般工作區啟動內容注入。
• agents.defaults.startupContext.*： 一次性的重設/啟動模型執行前置內容，包括近期每日 memory/*.md 檔案。純聊天 /new 與 /reset 指令會 在不叫用模型的情況下確認重設。
• skills.limits.*： 注入系統提示的精簡 Skills 清單。
• agents.defaults.contextLimits.*： 有界的執行階段摘錄與注入的執行階段所擁有區塊。
• memory.qmd.limits.*： 已索引記憶搜尋片段與注入大小。

只有當某個代理需要不同預算時，才使用對應的個別代理覆寫：

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextLimits.*

agents.defaults.startupContext

控制在重設/啟動模型執行時，於第一回合注入的啟動前置內容。 純聊天 /new 與 /reset 指令會在不叫用模型的情況下確認重設， 因此不會載入此前置內容。

{  agents: {    defaults: {      startupContext: {        enabled: true,        applyOn: ["new", "reset"],        dailyMemoryDays: 2,        maxFileBytes: 16384,        maxFileChars: 1200,        maxTotalChars: 2800,      },    },  },}

agents.defaults.contextLimits

有界執行階段內容表面的共用預設值。

{  agents: {    defaults: {      contextLimits: {        memoryGetMaxChars: 12000,        memoryGetDefaultLines: 120,        toolResultMaxChars: 16000,        postCompactionMaxChars: 1800,      },    },  },}

• memoryGetMaxChars：加入截斷中繼資料與延續通知前，預設的 memory_get 摘錄上限。
• memoryGetDefaultLines：省略 lines 時，預設的 memory_get 行視窗。
• toolResultMaxChars：用於持久化結果與溢位復原的即時工具結果上限。
• postCompactionMaxChars：Compaction 後重新整理注入期間使用的 AGENTS.md 摘錄上限。

agents.list[].contextLimits

共用 contextLimits 旋鈕的個別代理覆寫。省略的欄位會繼承自 agents.defaults.contextLimits。

{  agents: {    defaults: {      contextLimits: {        memoryGetMaxChars: 12000,        toolResultMaxChars: 16000,      },    },    list: [      {        id: "tiny-local",        contextLimits: {          memoryGetMaxChars: 6000,          toolResultMaxChars: 8000,        },      },    ],  },}

skills.limits.maxSkillsPromptChars

注入系統提示的精簡 Skills 清單全域上限。這 不會影響依需求讀取 SKILL.md 檔案。

{  skills: {    limits: {      maxSkillsPromptChars: 18000,    },  },}

agents.list[].skillsLimits.maxSkillsPromptChars

Skills 提示預算的個別代理覆寫。

{  agents: {    list: [      {        id: "tiny-local",        skillsLimits: {          maxSkillsPromptChars: 6000,        },      },    ],  },}

agents.defaults.imageMaxDimensionPx

在呼叫提供者前，逐字稿/工具圖片區塊中圖片最長邊的最大像素大小。 預設值：1200。

較低的值通常可降低大量截圖執行時的視覺 token 用量與請求酬載大小。 較高的值可保留更多視覺細節。

{  agents: { defaults: { imageMaxDimensionPx: 1200 } },}

agents.defaults.userTimezone

系統提示內容的時區（不是訊息時間戳）。會回退到主機時區。

{  agents: { defaults: { userTimezone: "America/Chicago" } },}

agents.defaults.timeFormat

系統提示中的時間格式。預設值：auto（作業系統偏好設定）。

{  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24}

agents.defaults.model

{  agents: {    defaults: {      models: {        "anthropic/claude-opus-4-6": { alias: "opus" },        "minimax/MiniMax-M2.7": { alias: "minimax" },      },      model: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["minimax/MiniMax-M2.7"],      },      imageModel: {        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],      },      imageGenerationModel: {        primary: "openai/gpt-image-2",        fallbacks: ["google/gemini-3.1-flash-image-preview"],      },      videoGenerationModel: {        primary: "qwen/wan2.6-t2v",        fallbacks: ["qwen/wan2.6-i2v"],      },      pdfModel: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["openai/gpt-5.4-mini"],      },      params: { cacheRetention: "long" }, // global default provider params      pdfMaxBytesMb: 10,      pdfMaxPages: 20,      thinkingDefault: "low",      verboseDefault: "off",      toolProgressDetail: "explain",      reasoningDefault: "off",      elevatedDefault: "on",      timeoutSeconds: 600,      mediaMaxMb: 5,      contextTokens: 200000,      maxConcurrent: 3,    },  },}

• model：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 字串形式只設定主要模型。
  • 物件形式會設定主要模型加上有順序的故障轉移模型。
• imageModel：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 由 image 工具路徑用作其視覺模型設定。
  • 也會在所選/預設模型無法接受影像輸入時，用作後援路由。
  • 建議使用明確的 provider/model 參照。為了相容性，也接受裸 ID；如果裸 ID 在 models.providers.*.models 中唯一符合一個已設定且支援影像的項目，OpenClaw 會將它限定到該供應商。不明確的已設定符合項目需要明確的供應商前綴。
• imageGenerationModel：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 由共用的影像生成功能，以及任何未來會產生影像的工具/Plugin 介面使用。
  • 典型值：google/gemini-3.1-flash-image-preview 用於原生 Gemini 影像生成，fal/fal-ai/flux/dev 用於 fal，openai/gpt-image-2 用於 OpenAI Images，或 openai/gpt-image-1.5 用於透明背景的 OpenAI PNG/WebP 輸出。
  • 如果你直接選取供應商/模型，也要設定相符的供應商驗證（例如 google/* 使用 GEMINI_API_KEY 或 GOOGLE_API_KEY，openai/gpt-image-2 / openai/gpt-image-1.5 使用 OPENAI_API_KEY 或 OpenAI Codex OAuth，fal/* 使用 FAL_KEY）。
  • 如果省略，image_generate 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，接著按供應商 ID 順序嘗試其餘已註冊的影像生成供應商。
• musicGenerationModel：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 由共用的音樂生成功能，以及內建的 music_generate 工具使用。
  • 典型值：google/lyria-3-clip-preview、google/lyria-3-pro-preview 或 minimax/music-2.6。
  • 如果省略，music_generate 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，接著按供應商 ID 順序嘗試其餘已註冊的音樂生成供應商。
  • 如果你直接選取供應商/模型，也要設定相符的供應商驗證/API 金鑰。
• videoGenerationModel：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 由共用的影片生成功能，以及內建的 video_generate 工具使用。
  • 典型值：qwen/wan2.6-t2v、qwen/wan2.6-i2v、qwen/wan2.6-r2v、qwen/wan2.6-r2v-flash 或 qwen/wan2.7-r2v。
  • 如果省略，video_generate 仍可推斷有驗證支援的供應商預設值。它會先嘗試目前的預設供應商，接著按供應商 ID 順序嘗試其餘已註冊的影片生成供應商。
  • 如果你直接選取供應商/模型，也要設定相符的供應商驗證/API 金鑰。
  • 隨附的 Qwen 影片生成供應商最多支援 1 個輸出影片、1 張輸入影像、4 個輸入影片、10 秒長度，以及供應商層級的 size、aspectRatio、resolution、audio 和 watermark 選項。
• pdfModel：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 由 pdf 工具用於模型路由。
  • 如果省略，PDF 工具會後援到 imageModel，再後援到已解析的工作階段/預設模型。
• pdfMaxBytesMb：當呼叫時未傳入 maxBytesMb 時，pdf 工具的預設 PDF 大小限制。
• pdfMaxPages：pdf 工具中，擷取後援模式預設考量的最大頁數。
• verboseDefault：代理的預設詳細程度。值："off"、"on"、"full"。預設："off"。
• toolProgressDetail：/verbose 工具摘要和進度草稿工具列的詳細模式。值："explain"（預設，精簡的人類可讀標籤）或 "raw"（可用時附加原始命令/詳細資料）。每個代理的 agents.list[].toolProgressDetail 會覆寫此預設值。
• reasoningDefault：代理的預設推理可見性。值："off"、"on"、"stream"。每個代理的 agents.list[].reasoningDefault 會覆寫此預設值。只有在未設定每則訊息或工作階段推理覆寫時，已設定的推理預設值才會套用於擁有者、已授權寄件者，或 operator-admin Gateway 情境。
• elevatedDefault：代理的預設提升輸出層級。值："off"、"on"、"ask"、"full"。預設："on"。
• model.primary：格式為 provider/model（例如 openai/gpt-5.5 用於 OpenAI API 金鑰或 Codex OAuth 存取）。如果省略供應商，OpenClaw 會先嘗試別名，再為該精確模型 ID 嘗試唯一的已設定供應商符合項目，之後才後援到已設定的預設供應商（已棄用的相容性行為，因此建議使用明確的 provider/model）。如果該供應商不再提供已設定的預設模型，OpenClaw 會後援到第一個已設定的供應商/模型，而不是暴露過時且已移除供應商的預設值。
• models：為 /model 設定的模型目錄與允許清單。每個項目可包含 alias（捷徑）和 params（供應商特定，例如 temperature、maxTokens、cacheRetention、context1m、responsesServerCompaction、responsesCompactThreshold、chat_template_kwargs、extra_body/extraBody）。
  • 使用 provider/* 項目，例如 "openai-codex/*": {} 或 "vllm/*": {}，可顯示所選供應商的所有已發現模型，而不需要手動列出每個模型 ID。
  • 安全編輯：使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 來新增項目。除非傳入 --replace，否則 config set 會拒絕會移除現有允許清單項目的替換。
  • 供應商範圍的設定/入門流程會將所選供應商模型合併到此對映，並保留已設定的無關供應商。
  • 對於直接 OpenAI Responses 模型，伺服器端 Compaction 會自動啟用。使用 params.responsesServerCompaction: false 停止注入 context_management，或使用 params.responsesCompactThreshold 覆寫閾值。請參閱 OpenAI 伺服器端 Compaction。
• params：套用於所有模型的全域預設供應商參數。設定於 agents.defaults.params（例如 { cacheRetention: "long" }）。
• params 合併優先順序（設定）：agents.defaults.params（全域基底）會被 agents.defaults.models["provider/model"].params（每個模型）覆寫，接著 agents.list[].params（符合的代理 ID）會依鍵覆寫。詳情請參閱 提示快取。
• params.extra_body/params.extraBody：進階傳遞 JSON，會合併到 OpenAI 相容代理的 api: "openai-completions" 要求本文中。如果它與產生的要求鍵衝突，額外本文會勝出；非原生 completions 路由之後仍會移除僅限 OpenAI 的 store。
• params.chat_template_kwargs：vLLM/OpenAI 相容的聊天範本引數，會合併到頂層 api: "openai-completions" 要求本文中。對於關閉思考的 vllm/nemotron-3-*，隨附的 vLLM Plugin 會自動傳送 enable_thinking: false 和 force_nonempty_content: true；明確的 chat_template_kwargs 會覆寫產生的預設值，而 extra_body.chat_template_kwargs 仍具最終優先權。對於 vLLM Qwen 思考控制，請在該模型項目上將 params.qwenThinkingFormat 設為 "chat-template" 或 "top-level"。
• compat.thinkingFormat：OpenAI 相容的思考負載樣式。對於 Qwen 樣式的頂層 enable_thinking，使用 "qwen"；對於支援要求層級聊天範本 kwargs 的 Qwen 系列後端（例如 vLLM）上的 chat_template_kwargs.enable_thinking，使用 "qwen-chat-template"。OpenClaw 會將停用的思考對應到 false，並將啟用的思考對應到 true。
• compat.supportedReasoningEfforts：每個模型的 OpenAI 相容推理強度清單。對於真正接受它的自訂端點，請包含 "xhigh"；接著 OpenClaw 會在命令選單、Gateway 工作階段列、工作階段修補驗證、代理 CLI 驗證，以及該已設定供應商/模型的 llm-task 驗證中公開 /think xhigh。當後端需要針對標準層級使用供應商特定值時，請使用 compat.reasoningEffortMap。
• params.preserveThinking：僅限 Z.AI 的保留思考選擇加入。啟用且思考開啟時，OpenClaw 會傳送 thinking.clear_thinking: false 並重播先前的 reasoning_content；請參閱 Z.AI 思考與保留思考。
• localService：本機/自託管模型伺服器的選用供應商層級程序管理器。當所選模型屬於該供應商時，OpenClaw 會探測 healthUrl（或 baseUrl + "/models"），如果端點已停用，則使用 args 啟動 command，最多等待 readyTimeoutMs，然後傳送模型要求。command 必須是絕對路徑。idleStopMs: 0 會讓程序持續執行直到 OpenClaw 結束；正值會在該數量的閒置毫秒後停止由 OpenClaw 產生的程序。請參閱 本機模型服務。
• 執行階段政策屬於供應商或模型，不屬於 agents.defaults。使用 models.providers.<provider>.agentRuntime 設定供應商範圍規則，或使用 agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime 設定模型特定規則。官方 OpenAI 供應商上的 OpenAI 代理模型預設會選取 Codex。
• 變更這些欄位的設定寫入器（例如 /models set、/models set-image，以及後援新增/移除命令）會儲存標準物件形式，並在可能時保留現有後援清單。
• maxConcurrent：跨工作階段的最大平行代理執行數（每個工作階段仍會序列化）。預設：4。

執行階段政策

{  models: {    providers: {      openai: {        agentRuntime: { id: "codex" },      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.5",      models: {        "anthropic/claude-opus-4-7": {          agentRuntime: { id: "claude-cli" },        },      },    },  },}

• id："auto"、"pi"、已註冊的 Plugin harness ID，或受支援的 CLI 後端別名。隨附的 Codex Plugin 會註冊 codex；隨附的 Anthropic Plugin 會提供 claude-cli CLI 後端。
• id: "auto" 可讓已註冊的 Plugin harness 認領受支援的回合，並在沒有符合的 harness 時使用 PI。明確的 Plugin runtime（例如 id: "codex"）需要該 harness，且在不可用或失敗時會封閉失敗。
• 整個代理的執行階段鍵是舊版項目。agents.defaults.agentRuntime、agents.list[].agentRuntime、工作階段執行階段固定值，以及 OPENCLAW_AGENT_RUNTIME 會被執行階段選取忽略。執行 openclaw doctor --fix 以移除過時值。
• OpenAI 代理模型預設使用 Codex harness；當你想讓它明確時，供應商/模型 agentRuntime.id: "codex" 仍然有效。
• 對於 Claude CLI 部署，建議使用 model: "anthropic/claude-opus-4-7" 加上模型範圍的 agentRuntime.id: "claude-cli"。舊版 claude-cli/claude-opus-4-7 模型參照仍可為了相容性而運作，但新設定應保持供應商/模型選取的標準形式，並將執行後端放在供應商/模型執行階段政策中。
• 這只控制文字代理回合執行。媒體生成、視覺、PDF、音樂、影片和 TTS 仍使用其供應商/模型設定。

內建別名簡寫（只在模型位於 agents.defaults.models 時套用）：

你設定的別名一律優先於預設值。

Z.AI GLM-4.x 模型會自動啟用思考模式，除非你設定 --thinking off，或自行定義 agents.defaults.models["zai/<model>"].params.thinking。 Z.AI 模型預設會啟用 tool_stream 以支援工具呼叫串流。將 agents.defaults.models["zai/<model>"].params.tool_stream 設為 false 可停用此功能。 Anthropic Claude 4.6 模型在未設定明確思考層級時，預設使用 adaptive 思考。

agents.defaults.cliBackends

文字專用備援執行的選用 CLI 後端（無工具呼叫）。適合作為 API 提供者失敗時的備用方案。

{  agents: {    defaults: {      cliBackends: {        "codex-cli": {          command: "/opt/homebrew/bin/codex",        },        "my-cli": {          command: "my-cli",          args: ["--json"],          output: "json",          modelArg: "--model",          sessionArg: "--session",          sessionMode: "existing",          systemPromptArg: "--system",          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.          systemPromptWhen: "first",          imageArg: "--image",          imageMode: "repeat",        },      },    },  },}

• CLI 後端以文字優先；工具一律停用。
• 設定 sessionArg 時支援工作階段。
• imageArg 接受檔案路徑時支援影像傳遞。
• reseedFromRawTranscriptWhenUncompacted: true 可讓後端在第一個 Compaction 摘要存在之前，從有界的原始 OpenClaw 逐字稿尾端復原安全的已失效工作階段。驗證設定檔或憑證 epoch 變更仍絕不會以原始內容重新播種。

agents.defaults.systemPromptOverride

以固定字串取代整個由 OpenClaw 組裝的系統提示。可在預設層級（agents.defaults.systemPromptOverride）或個別 agent（agents.list[].systemPromptOverride）設定。個別 agent 的值優先；空值或只有空白的值會被忽略。適合受控的提示實驗。

{  agents: {    defaults: {      systemPromptOverride: "You are a helpful assistant.",    },  },}

agents.defaults.promptOverlays

依模型家族套用、與提供者無關的提示覆蓋。GPT-5 家族模型 ID 會跨提供者取得共用行為契約；personality 只控制友善互動風格層。

{  agents: {    defaults: {      promptOverlays: {        gpt5: {          personality: "friendly", // friendly | on | off        },      },    },  },}

• "friendly"（預設）與 "on" 會啟用友善互動風格層。
• "off" 只停用友善層；帶標記的 GPT-5 行為契約仍會啟用。
• 未設定此共用設定時，仍會讀取舊版 plugins.entries.openai.config.personality。

agents.defaults.heartbeat

定期 Heartbeat 執行。

{  agents: {    defaults: {      heartbeat: {        every: "30m", // 0m disables        model: "openai/gpt-5.4-mini",        includeReasoning: false,        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes        session: "main",        to: "+15555550123",        directPolicy: "allow", // allow (default) | block        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...        prompt: "Read HEARTBEAT.md if it exists...",        ackMaxChars: 300,        suppressToolErrorWarnings: false,        timeoutSeconds: 45,      },    },  },}

• every：持續時間字串（ms/s/m/h）。預設：30m（API 金鑰驗證）或 1h（OAuth 驗證）。設為 0m 可停用。
• includeSystemPromptSection：為 false 時，會從系統提示中省略 Heartbeat 區段，並略過將 HEARTBEAT.md 注入啟動內容。預設：true。
• suppressToolErrorWarnings：為 true 時，會在 Heartbeat 執行期間抑制工具錯誤警告酬載。
• timeoutSeconds：Heartbeat agent 回合在中止前允許的最長秒數。未設定時使用 agents.defaults.timeoutSeconds。
• directPolicy：直接/DM 傳送政策。allow（預設）允許傳送至直接目標。block 會抑制直接目標傳送並發出 reason=dm-blocked。
• lightContext：為 true 時，Heartbeat 執行會使用輕量啟動內容，且只保留工作區啟動檔案中的 HEARTBEAT.md。
• isolatedSession：為 true 時，每個 Heartbeat 都會在沒有先前對話記錄的新工作階段中執行。與 cron sessionTarget: "isolated" 相同的隔離模式。將每次 Heartbeat 的 token 成本從約 100K 降至約 2-5K token。
• skipWhenBusy：為 true 時，Heartbeat 執行會在該 agent 的額外忙碌通道上延後：其自身以工作階段為鍵的 subagent 或巢狀命令工作。Cron 通道一律會延後 Heartbeat，即使未設定此旗標。
• 個別 agent：設定 agents.list[].heartbeat。當任何 agent 定義 heartbeat 時，只有那些 agent 會執行 Heartbeat。
• Heartbeat 會執行完整的 agent 回合——較短的間隔會消耗更多 token。

agents.defaults.compaction

{  agents: {    defaults: {      compaction: {        mode: "safeguard", // default | safeguard        provider: "my-provider", // id of a registered compaction provider plugin (optional)        timeoutSeconds: 900,        reserveTokensFloor: 24000,        keepRecentTokens: 50000,        identifierPolicy: "strict", // strict | off | custom        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom        qualityGuard: { enabled: true, maxRetries: 1 },        midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger        notifyUser: true, // send brief notices when compaction starts and completes (default: false)        memoryFlush: {          enabled: true,          model: "ollama/qwen3:8b", // optional memory-flush-only model override          softThresholdTokens: 6000,          systemPrompt: "Session nearing compaction. Store durable memories now.",          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",        },      },    },  },}

• mode：default 或 safeguard（長歷史記錄的分塊摘要）。請參閱 Compaction。
• provider：已註冊 Compaction 提供者 Plugin 的 ID。設定後會呼叫提供者的 summarize()，而不是內建 LLM 摘要。失敗時會退回內建摘要。設定提供者會強制 mode: "safeguard"。請參閱 Compaction。
• timeoutSeconds：單次 Compaction 操作在 OpenClaw 中止前允許的最長秒數。預設：900。
• keepRecentTokens：Pi 截點預算，用於逐字保留最近的逐字稿尾端。手動 /compact 會在明確設定時遵循此值；否則手動 Compaction 是硬性檢查點。
• identifierPolicy：strict（預設）、off 或 custom。strict 會在 Compaction 摘要期間前置內建的不透明識別碼保留指引。
• identifierInstructions：選用的自訂識別碼保留文字，於 identifierPolicy=custom 時使用。
• qualityGuard：對 safeguard 摘要執行格式異常輸出的重試檢查。safeguard 模式預設啟用；設為 enabled: false 可略過稽核。
• midTurnPrecheck：選用的 Pi 工具迴圈壓力檢查。當 enabled: true 時，OpenClaw 會在工具結果附加後、下一次模型呼叫前檢查內容壓力。若內容已無法容納，會在提交提示前中止目前嘗試，並重用既有的預檢復原路徑以截斷工具結果，或執行 Compaction 後重試。可搭配 default 與 safeguard Compaction 模式使用。預設：停用。
• postCompactionSections：選用的 AGENTS.md H2/H3 區段名稱，用於 Compaction 後重新注入。預設為 ["Session Startup", "Red Lines"]；設為 [] 可停用重新注入。未設定或明確設為該預設組合時，也會接受較舊的 Every Session/Safety 標題作為舊版備援。
• model：僅用於 Compaction 摘要的選用 provider/model-id 覆寫。當主要工作階段應保留一個模型，但 Compaction 摘要應在另一個模型上執行時使用；未設定時，Compaction 會使用工作階段的主要模型。
• maxActiveTranscriptBytes：選用的位元組閾值（number 或像 "20mb" 的字串），當作用中的 JSONL 超過閾值時，會在執行前觸發一般本機 Compaction。需要 truncateAfterCompaction，以便成功 Compaction 後可輪替至較小的後繼逐字稿。未設定或為 0 時停用。
• notifyUser：為 true 時，會在 Compaction 開始與完成時向使用者傳送簡短通知（例如「正在壓縮內容...」與「Compaction 完成」）。預設停用，以保持 Compaction 靜默。
• memoryFlush：在自動 Compaction 前進行的靜默 agentic 回合，用於儲存持久記憶。當此維護回合應保留在本機模型上時，將 model 設為確切的提供者/模型，例如 ollama/qwen3:8b；此覆寫不會繼承作用中工作階段的備援鏈。工作區唯讀時會略過。

agents.defaults.runRetries

嵌入式 Pi 執行器的外層執行迴圈重試迭代邊界，用於防止失敗復原期間發生無限執行迴圈。請注意，此設定目前只適用於嵌入式 agent 執行環境，不適用於 ACP 或 CLI 執行環境。

{  agents: {    defaults: {      runRetries: {        base: 24,        perProfile: 8,        min: 32,        max: 160,      },    },    list: [      {        id: "main",        runRetries: { max: 50 }, // optional per-agent overrides      },    ],  },}

• base：外層執行迴圈的基本執行重試迭代次數。預設：24。
• perProfile：每個備援設定檔候選項所授予的額外執行重試迭代次數。預設：8。
• min：執行重試迭代次數的絕對下限。預設：32。
• max：執行重試迭代次數的絕對上限，用於防止失控執行。預設：160。

agents.defaults.contextPruning

在傳送給 LLM 前，從記憶體內容中修剪舊的工具結果。不會修改磁碟上的工作階段歷史記錄。

{  agents: {    defaults: {      contextPruning: {        mode: "cache-ttl", // off | cache-ttl        ttl: "1h", // duration (ms/s/m/h), default unit: minutes        keepLastAssistants: 3,        softTrimRatio: 0.3,        hardClearRatio: 0.5,        minPrunableToolChars: 50000,        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },        tools: { deny: ["browser", "canvas"] },      },    },  },}

行為詳細資料請參閱工作階段修剪。

區塊串流

{  agents: {    defaults: {      blockStreamingDefault: "off", // on | off      blockStreamingBreak: "text_end", // text_end | message_end      blockStreamingChunk: { minChars: 800, maxChars: 1200 },      blockStreamingCoalesce: { idleMs: 1000 },      humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)    },  },}

• 非 Telegram 通道需要明確設定 *.blockStreaming: true 才能啟用區塊回覆。
• 通道覆寫：channels.<channel>.blockStreamingCoalesce（以及各帳號變體）。Signal/Slack/Discord/Google Chat 預設為 minChars: 1500。
• humanDelay：區塊回覆之間的隨機暫停。natural = 800–2500ms。每個代理的覆寫：agents.list[].humanDelay。

行為與分塊詳細資料請參閱串流。

輸入指示器

{  agents: {    defaults: {      typingMode: "instant", // never | instant | thinking | message      typingIntervalSeconds: 6,    },  },}

• 預設值：直接聊天/提及使用 instant，未提及的群組聊天使用 message。
• 每個工作階段的覆寫：session.typingMode、session.typingIntervalSeconds。

請參閱輸入指示器。

agents.defaults.sandbox

嵌入式代理的選用沙箱化。完整指南請參閱沙箱化。

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        backend: "docker", // docker | ssh | openshell        scope: "agent", // session | agent | shared        workspaceAccess: "none", // none | ro | rw        workspaceRoot: "~/.openclaw/sandboxes",        docker: {          image: "openclaw-sandbox:bookworm-slim",          containerPrefix: "openclaw-sbx-",          workdir: "/workspace",          readOnlyRoot: true,          tmpfs: ["/tmp", "/var/tmp", "/run"],          network: "none",          user: "1000:1000",          capDrop: ["ALL"],          env: { LANG: "C.UTF-8" },          setupCommand: "apt-get update && apt-get install -y git curl jq",          pidsLimit: 256,          memory: "1g",          memorySwap: "2g",          cpus: 1,          ulimits: {            nofile: { soft: 1024, hard: 2048 },            nproc: 256,          },          seccompProfile: "/path/to/seccomp.json",          apparmorProfile: "openclaw-sandbox",          dns: ["1.1.1.1", "8.8.8.8"],          extraHosts: ["internal.service:10.0.0.5"],          binds: ["/home/user/source:/source:rw"],        },        ssh: {          target: "user@gateway-host:22",          command: "ssh",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // SecretRefs / inline contents also supported:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },        browser: {          enabled: false,          image: "openclaw-sandbox-browser:bookworm-slim",          network: "openclaw-sandbox-browser",          cdpPort: 9222,          cdpSourceRange: "172.21.0.1/32",          vncPort: 5900,          noVncPort: 6080,          headless: false,          enableNoVnc: true,          allowHostControl: false,          autoStart: true,          autoStartTimeoutMs: 12000,        },        prune: {          idleHours: 24,          maxAgeDays: 7,        },      },    },  },  tools: {    sandbox: {      tools: {        allow: [          "exec",          "process",          "read",          "write",          "edit",          "apply_patch",          "sessions_list",          "sessions_history",          "sessions_send",          "sessions_spawn",          "session_status",        ],        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],      },    },  },}

{plugins: {  entries: {    openshell: {      enabled: true,      config: {        mode: "mirror", // mirror | remote        from: "openclaw",        remoteWorkspaceDir: "/sandbox",        remoteAgentWorkspaceDir: "/agent",        gateway: "lab", // optional        gatewayEndpoint: "https://lab.example", // optional        policy: "strict", // optional OpenShell policy id        providers: ["openai"], // optional        autoProviders: true,        timeoutSeconds: 120,      },    },  },},}

瀏覽器沙箱化與 sandbox.docker.binds 僅限 Docker。

建置映像（從來源簽出）：

scripts/sandbox-setup.sh           # main sandbox imagescripts/sandbox-browser-setup.sh   # optional browser image

若 npm 安裝沒有來源簽出，請參閱沙箱化 § 映像與設定，了解內嵌 docker build 命令。

agents.list（每個代理覆寫）

使用 agents.list[].tts 為代理程式設定自己的 TTS 提供者、語音、模型、 風格或自動 TTS 模式。代理程式區塊會深度合併到全域 messages.tts 之上，因此共用憑證可以維持在同一處，而個別 代理程式只覆寫其需要的語音或提供者欄位。作用中代理程式的 覆寫會套用到自動語音回覆、/tts audio、/tts status，以及 tts 代理程式工具。請參閱文字轉語音 以取得提供者範例與優先順序。

{  agents: {    list: [      {        id: "main",        default: true,        name: "Main Agent",        workspace: "~/.openclaw/workspace",        agentDir: "~/.openclaw/agents/main/agent",        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }        thinkingDefault: "high", // per-agent thinking level override        reasoningDefault: "on", // per-agent reasoning visibility override        fastModeDefault: false, // per-agent fast mode override        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key        tts: {          providers: {            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },          },        },        skills: ["docs-search"], // replaces agents.defaults.skills when set        identity: {          name: "Samantha",          theme: "helpful sloth",          emoji: "🦥",          avatar: "avatars/samantha.png",        },        groupChat: { mentionPatterns: ["@openclaw"] },        sandbox: { mode: "off" },        runtime: {          type: "acp",          acp: {            agent: "codex",            backend: "acpx",            mode: "persistent",            cwd: "/workspace/openclaw",          },        },        subagents: { allowAgents: ["*"] },        tools: {          profile: "coding",          allow: ["browser"],          deny: ["canvas"],          elevated: { enabled: true },        },      },    ],  },}

• id：穩定的代理程式 ID（必填）。
• default：設定多個時，第一個生效（會記錄警告）。若未設定任何項目，清單中的第一個項目會成為預設值。
• model：字串形式會設定嚴格的每代理程式主要模型，且沒有模型後援；物件形式 { primary } 也同樣嚴格，除非你加入 fallbacks。使用 { primary, fallbacks: [...] } 讓該代理程式選擇加入後援，或使用 { primary, fallbacks: [] } 明確指定嚴格行為。只覆寫 primary 的 Cron 工作仍會繼承預設後援，除非你設定 fallbacks: []。
• params：每代理程式的串流參數，會合併到 agents.defaults.models 中選取的模型項目之上。使用此項目設定代理程式專屬覆寫，例如 cacheRetention、temperature 或 maxTokens，而不必複製整個模型目錄。
• tts：選用的每代理程式文字轉語音覆寫。此區塊會深度合併到 messages.tts 之上，因此請將共用提供者憑證與後援政策保留在 messages.tts，並在這裡只設定角色專屬值，例如提供者、語音、模型、風格或自動模式。
• skills：選用的每代理程式技能允許清單。若省略，代理程式會在有設定時繼承 agents.defaults.skills；明確清單會取代預設值而非合併，且 [] 表示沒有 Skills。
• thinkingDefault：選用的每代理程式預設思考等級（off | minimal | low | medium | high | xhigh | adaptive | max）。當未設定每訊息或工作階段覆寫時，會為此代理程式覆寫 agents.defaults.thinkingDefault。所選提供者/模型設定檔會控制哪些值有效；對於 Google Gemini，adaptive 會保留提供者擁有的動態思考（Gemini 3/3.1 省略 thinkingLevel，Gemini 2.5 使用 thinkingBudget: -1）。
• reasoningDefault：選用的每代理程式預設推理可見性（on | off | stream）。當未設定每訊息或工作階段推理覆寫時，會為此代理程式覆寫 agents.defaults.reasoningDefault。
• fastModeDefault：選用的每代理程式快速模式預設值（true | false）。當未設定每訊息或工作階段快速模式覆寫時套用。
• models：選用的每代理程式模型目錄/執行階段覆寫，以完整 provider/model ID 作為鍵。使用 models["provider/model"].agentRuntime 設定每代理程式執行階段例外。
• runtime：選用的每代理程式執行階段描述元。當代理程式應預設使用 ACP harness 工作階段時，請搭配 runtime.acp 預設值（agent、backend、mode、cwd）使用 type: "acp"。
• identity.avatar：相對於工作區的路徑、http(s) URL，或 data: URI。
• identity 會衍生預設值：ackReaction 來自 emoji，mentionPatterns 來自 name/emoji。
• subagents.allowAgents：明確 sessions_spawn.agentId 目標的代理程式 ID 允許清單（["*"] = 任意；預設：僅同一代理程式）。當應允許以自身為目標的 agentId 呼叫時，請包含請求者 ID。
• 沙箱繼承防護：若請求者工作階段已套用沙箱，sessions_spawn 會拒絕會以非沙箱方式執行的目標。
• subagents.requireAgentId：為 true 時，封鎖省略 agentId 的 sessions_spawn 呼叫（強制明確選擇設定檔；預設：false）。

多代理程式路由

在單一 Gateway 內執行多個隔離代理程式。請參閱多代理程式。

{  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" } },  ],}

繫結比對欄位

• type（選用）：route 用於一般路由（缺少 type 時預設為 route），acp 用於持久 ACP 對話繫結。
• match.channel（必填）
• match.accountId（選用；* = 任意帳號；省略 = 預設帳號）
• match.peer（選用；{ kind: direct|group|channel, id }）
• match.guildId / match.teamId（選用；通道專屬）
• acp（選用；僅適用於 type: "acp"）：{ mode, label, cwd, backend }

確定性比對順序：

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId（精確，無 peer/guild/team）
5. match.accountId: "*"（整個通道）
6. 預設代理程式

在每一層中，第一個相符的 bindings 項目會生效。

對於 type: "acp" 項目，OpenClaw 會依確切對話身分解析（match.channel + 帳號 + match.peer.id），且不使用上述路由繫結層級順序。

每代理程式存取設定檔

{agents: {  list: [    {      id: "personal",      workspace: "~/.openclaw/workspace-personal",      sandbox: { mode: "off" },    },  ],},}

{agents: {  list: [    {      id: "family",      workspace: "~/.openclaw/workspace-family",      sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },      tools: {        allow: [          "read",          "sessions_list",          "sessions_history",          "sessions_send",          "sessions_spawn",          "session_status",        ],        deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],      },    },  ],},}

{agents: {  list: [    {      id: "public",      workspace: "~/.openclaw/workspace-public",      sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },      tools: {        allow: [          "sessions_list",          "sessions_history",          "sessions_send",          "sessions_spawn",          "session_status",          "whatsapp",          "telegram",          "slack",          "discord",          "gateway",        ],        deny: [          "read",          "write",          "edit",          "apply_patch",          "exec",          "process",          "browser",          "canvas",          "nodes",          "cron",          "gateway",          "image",        ],      },    },  ],},}

請參閱多代理程式沙箱與工具以了解優先順序詳細資訊。

工作階段

{  session: {    scope: "per-sender",    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer    identityLinks: {      alice: ["telegram:123456789", "discord:987654321012345678"],    },    reset: {      mode: "daily", // daily | idle      atHour: 4,      idleMinutes: 60,    },    resetByType: {      thread: { mode: "daily", atHour: 4 },      direct: { mode: "idle", idleMinutes: 240 },      group: { mode: "idle", idleMinutes: 120 },    },    resetTriggers: ["/new", "/reset"],    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",    maintenance: {      mode: "warn", // warn | enforce      pruneAfter: "30d",      maxEntries: 500,      resetArchiveRetention: "30d", // duration or false      maxDiskBytes: "500mb", // optional hard budget      highWaterBytes: "400mb", // optional cleanup target    },    threadBindings: {      enabled: true,      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)      maxAgeHours: 0, // default hard max age in hours (`0` disables)    },    mainKey: "main", // legacy (runtime always uses "main")    agentToAgent: { maxPingPongTurns: 5 },    sendPolicy: {      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],      default: "allow",    },  },}

訊息

{  messages: {    responsePrefix: "🦞", // or "auto"    ackReaction: "👀",    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all    removeAckAfterReply: false,    queue: {      mode: "steer", // steer | queue (legacy one-at-a-time) | followup | collect | steer-backlog | steer+backlog | interrupt      debounceMs: 500,      cap: 20,      drop: "summarize", // old | new | summarize      byChannel: {        whatsapp: "steer",        telegram: "steer",      },    },    inbound: {      debounceMs: 2000, // 0 disables      byChannel: {        whatsapp: 5000,        slack: 1500,      },    },  },}

回應前綴

依頻道/帳號覆寫：channels.<channel>.responsePrefix、channels.<channel>.accounts.<id>.responsePrefix。

解析順序（最具體者優先）：帳號 → 頻道 → 全域。"" 會停用並停止串接。"auto" 會衍生 [{identity.name}]。

範本變數：

變數不區分大小寫。{think} 是 {thinkingLevel} 的別名。

Ack 反應

• 預設為作用中代理的 identity.emoji，否則為 "👀"。設為 "" 可停用。
• 依頻道覆寫：channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。
• 解析順序：帳號 → 頻道 → messages.ackReaction → 身分後援。
• 範圍：group-mentions（預設）、group-all、direct、all。
• removeAckAfterReply：在支援反應的頻道（例如 Slack、Discord、Telegram、WhatsApp 與 iMessage）上，回覆後移除 ack。
• messages.statusReactions.enabled：在 Slack、Discord 與 Telegram 上啟用生命週期狀態反應。 在 Slack 與 Discord 上，未設定時會在 ack 反應作用中時保持狀態反應啟用。 在 Telegram 上，請明確設為 true 以啟用生命週期狀態反應。

傳入防抖

將同一傳送者快速送出的純文字訊息批次合併為單一代理輪次。媒體/附件會立即刷新。控制指令會略過防抖。

TTS（文字轉語音）

{  messages: {    tts: {      auto: "always", // off | always | inbound | tagged      mode: "final", // final | all      provider: "elevenlabs",      summaryModel: "openai/gpt-4.1-mini",      modelOverrides: { enabled: true },      maxTextLength: 4000,      timeoutMs: 30000,      prefsPath: "~/.openclaw/settings/tts.json",      providers: {        elevenlabs: {          apiKey: "elevenlabs_api_key",          baseUrl: "https://api.elevenlabs.io",          voiceId: "voice_id",          modelId: "eleven_multilingual_v2",          seed: 42,          applyTextNormalization: "auto",          languageCode: "en",          voiceSettings: {            stability: 0.5,            similarityBoost: 0.75,            style: 0.0,            useSpeakerBoost: true,            speed: 1.0,          },        },        microsoft: {          voice: "en-US-AvaMultilingualNeural",          lang: "en-US",          outputFormat: "audio-24khz-48kbitrate-mono-mp3",        },        openai: {          apiKey: "openai_api_key",          baseUrl: "https://api.openai.com/v1",          model: "gpt-4o-mini-tts",          voice: "alloy",        },      },    },  },}

• auto 控制預設自動 TTS 模式：off、always、inbound 或 tagged。/tts on|off 可以覆寫本機偏好設定，/tts status 會顯示有效狀態。
• summaryModel 會覆寫 agents.defaults.model.primary 以用於自動摘要。
• modelOverrides 預設啟用；modelOverrides.allowProvider 預設為 false（需選擇加入）。
• API 金鑰會後援至 ELEVENLABS_API_KEY/XI_API_KEY 與 OPENAI_API_KEY。
• 內建語音提供者由 Plugin 擁有。如果設定了 plugins.allow，請包含你想使用的每個 TTS 提供者 Plugin，例如 Edge TTS 的 microsoft。舊版 edge 提供者 ID 可作為 microsoft 的別名。
• providers.openai.baseUrl 會覆寫 OpenAI TTS 端點。解析順序為設定，接著是 OPENAI_TTS_BASE_URL，再來是 https://api.openai.com/v1。
• 當 providers.openai.baseUrl 指向非 OpenAI 端點時，OpenClaw 會將其視為 OpenAI 相容的 TTS 伺服器，並放寬模型/語音驗證。

Talk

Talk 模式（macOS/iOS/Android）的預設值。

{  talk: {    provider: "elevenlabs",    providers: {      elevenlabs: {        voiceId: "elevenlabs_voice_id",        voiceAliases: {          Clawd: "EXAVITQu4vr4xnSDxMaL",          Roger: "CwhRBWXzGAHq8TQ4Fs17",        },        modelId: "eleven_v3",        outputFormat: "mp3_44100_128",        apiKey: "elevenlabs_api_key",      },      mlx: {        modelId: "mlx-community/Soprano-80M-bf16",      },      system: {},    },    consultThinkingLevel: "low",    consultFastMode: true,    speechLocale: "ru-RU",    silenceTimeoutMs: 1500,    interruptOnSpeech: true,    realtime: {      provider: "openai",      providers: {        openai: {          model: "gpt-realtime-2",          voice: "cedar",        },      },      instructions: "Speak warmly and keep answers brief.",      mode: "realtime",      transport: "webrtc",      brain: "agent-consult",    },  },}

• 設定多個 Talk 提供者時，talk.provider 必須符合 talk.providers 中的某個鍵。
• 舊版扁平 Talk 鍵（talk.voiceId、talk.voiceAliases、talk.modelId、talk.outputFormat、talk.apiKey）僅供相容性使用。執行 openclaw doctor --fix 可將持久化設定重寫為 talk.providers.<provider>。
• 語音 ID 會後援至 ELEVENLABS_VOICE_ID 或 SAG_VOICE_ID。
• providers.*.apiKey 接受純文字字串或 SecretRef 物件。
• ELEVENLABS_API_KEY 後援僅在未設定 Talk API 金鑰時套用。
• providers.*.voiceAliases 可讓 Talk 指令使用易讀名稱。
• providers.mlx.modelId 選取 macOS local MLX 輔助程式使用的 Hugging Face 儲存庫。如果省略，macOS 會使用 mlx-community/Soprano-80M-bf16。
• macOS MLX 播放會在存在時透過內建 openclaw-mlx-tts 輔助程式執行，或使用 PATH 上的可執行檔；OPENCLAW_MLX_TTS_BIN 會覆寫開發用的輔助程式路徑。
• consultThinkingLevel 控制 Control UI Talk 即時 openclaw_agent_consult 呼叫背後完整 OpenClaw 代理執行的思考層級。保留未設定可保留一般工作階段/模型行為。
• consultFastMode 會為 Control UI Talk 即時諮詢設定一次性的快速模式覆寫，而不變更工作階段的一般快速模式設定。
• speechLocale 設定 iOS/macOS Talk 語音辨識使用的 BCP 47 語系 ID。保留未設定會使用裝置預設值。
• silenceTimeoutMs 控制 Talk 模式在使用者靜默後等待多久才送出對話紀錄。未設定時會保留平台預設暫停時間窗（macOS 與 Android 為 700 ms，iOS 為 900 ms）。
• realtime.instructions 會將面向提供者的系統指示附加到 OpenClaw 內建即時提示，因此可在不失去預設 openclaw_agent_consult 指引的情況下設定語音風格。

相關

• 設定參考 — 所有其他設定鍵
• 設定 — 常見工作與快速設定
• 設定範例