設定 — 代理程式

​

代理程式預設值

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skills

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // 繼承 github、weather
      { id: "docs", skills: ["docs-search"] }, // 取代預設值
      { id: "locked-down", skills: [] }, // 無 Skills
    ],
  },
}

• 省略 agents.defaults.skills 表示預設不限制 Skills。
• 省略 agents.list[].skills 以繼承預設值。
• 設定 agents.list[].skills: [] 表示無 Skills。
• 非空的 agents.list[].skills 清單是該代理程式的最終集合； 不會與預設值合併。

​

agents.defaults.skipBootstrap

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

​

agents.defaults.skipOptionalBootstrapFiles

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

​

agents.defaults.contextInjection

• "continuation-skip"：安全的續接回合（完成的助理回應之後）會略過重新注入工作區啟動內容，以減少提示詞大小。心跳偵測執行和壓縮後重試仍會重建脈絡。
• "never"：在每個回合停用工作區啟動和脈絡檔案注入。僅對完全自行管理提示詞生命週期的代理程式使用此值（自訂脈絡引擎、建置自身脈絡的原生執行階段，或不需啟動檔案的專用工作流程）。心跳偵測和壓縮復原回合也會略過注入。

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

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

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

​

個別代理程式啟動設定檔覆寫

{
  agents: {
    defaults: {
      contextInjection: "continuation-skip",
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 60000,
    },
    list: [
      {
        id: "strict-worker",
        contextInjection: "always",
        bootstrapMaxChars: 50000,
        bootstrapTotalMaxChars: 300000,
      },
    ],
  },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off"：永不將截斷通知文字注入系統提示詞。
• "once"：每個唯一截斷簽章只注入一次精簡通知。
• "always"：存在截斷時，每次執行都注入精簡通知（建議）。

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

​

脈絡預算所有權對照表

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextInjection
• agents.list[].bootstrapMaxChars
• agents.list[].bootstrapTotalMaxChars
• agents.list[].contextLimits.*

​

agents.defaults.startupContext

{
  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,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars：加入截斷中繼資料與續接通知前， 預設 memory_get 摘錄上限。
• memoryGetDefaultLines：省略 lines 時，預設 memory_get 行視窗。
• toolResultMaxChars：進階即時工具結果上限，用於持久化 結果與溢位復原。未設定時會使用模型脈絡自動上限： 低於 100K token 時為 16000 字元，100K+ token 時為 32000 字元，200K+ token 時為 64000 字元。長脈絡模型可接受最高 1000000 的明確值， 但有效上限仍受限於模型脈絡視窗約 30%。 openclaw doctor --deep 會列印有效上限， 且 doctor 只會在明確覆寫已過時或沒有作用時發出警告。
• postCompactionMaxChars：壓縮後 重新整理注入期間使用的 AGENTS.md 摘錄上限。

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: { memoryGetMaxChars: 12000 },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000, // 此代理程式的進階上限
        },
      },
    ],
  },
}

​

skills.limits.maxSkillsPromptChars

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

​

agents.list[].skillsLimits.maxSkillsPromptChars

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

​

agents.defaults.imageMaxDimensionPx

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

​

agents.defaults.imageQuality

• auto：依模型限制與圖片數量調整。
• efficient：偏好較小圖片，以降低 token 與位元組用量。
• balanced：使用標準的折衷階梯。
• high：為截圖、圖表和文件圖片保留更多細節。

{
  agents: { defaults: { imageQuality: "auto" } },
}

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

{
  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"],
      },
      utilityModel: "openai/gpt-5.4-mini",
      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: 4,
    },
  },
}

• model：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 字串形式只設定主要模型。
  • 物件形式會設定主要模型加上有序的容錯移轉模型。
• utilityModel：選用的 provider/model 參照或別名，用於短小的內部工作。它目前支援產生的 Control UI 工作階段標題、Telegram DM 主題標題，以及 Discord 自動討論串標題。未設定時，這些工作會退回使用代理的主要模型；agents.list[].utilityModel 會覆寫預設值，而作業特定的模型覆寫會優先於兩者。公用工作會進行獨立的模型呼叫，並將工作特定內容傳送給選定的模型提供者。Dashboard 標題產生最多會傳送第一則非命令訊息的前 1,000 個字元。請選擇符合你的成本與資料處理需求的提供者。
• imageModel：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 由 image 工具路徑用作其視覺模型設定。
  • 當選定/預設模型無法接受圖片輸入時，也會用作備援路由。
  • 建議使用明確的 provider/model 參照。為了相容性，也接受裸 ID；如果裸 ID 在 models.providers.*.models 中唯一符合已設定且支援圖片的項目，OpenClaw 會將它限定到該提供者。若已設定的符合項目不明確，則需要明確的提供者前綴。
• imageGenerationModel：接受字串（"provider/model"）或物件（{ primary, fallbacks }）。
  • 由共用圖片產生能力，以及任何未來會產生圖片的工具/外掛介面使用。
  • 典型值：原生 Gemini 圖片產生使用 google/gemini-3.1-flash-image-preview，fal 使用 fal/fal-ai/flux/dev，OpenAI Images 使用 openai/gpt-image-2，或透明背景 OpenAI PNG/WebP 輸出使用 openai/gpt-image-1.5。
  • 如果你直接選取提供者/模型，也請設定相符的提供者驗證（例如 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 閘道情境。
• elevatedDefault：代理的預設提升輸出層級。值："off"、"on"、"ask"、"full"。預設值："on"。
• model.primary：格式為 provider/model（例如 OpenAI API 金鑰或 Codex OAuth 存取使用 openai/gpt-5.5）。如果省略提供者，OpenClaw 會先嘗試別名，接著嘗試該確切模型 ID 的唯一已設定提供者符合項目，最後才退回到已設定的預設提供者（已淘汰的相容行為，因此建議使用明確的 provider/model）。如果該提供者不再公開已設定的預設模型，OpenClaw 會退回到第一個已設定的提供者/模型，而不是顯示過時的已移除提供者預設值。
• models：已設定的模型目錄，以及 /model 的允許清單。每個項目可包含 alias（捷徑）和 params（提供者特定，例如 temperature、maxTokens、cacheRetention、context1m、responsesServerCompaction、responsesCompactThreshold、OpenRouter provider 路由、chat_template_kwargs、extra_body/extraBody）。
  • 使用 "openai/*": {} 或 "vllm/*": {} 等 provider/* 項目，可顯示所選提供者的所有已發現模型，而不必手動列出每個模型 ID。
  • 當該提供者的每個動態發現模型都應使用相同執行階段時，請將 agentRuntime 加到 provider/* 項目。精確的 provider/model 執行階段政策仍優先於萬用字元。
  • 安全編輯：使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 新增項目。除非傳入 --replace，否則 config set 會拒絕會移除既有允許清單項目的取代。
  • 提供者範圍的設定/入門流程會將所選提供者模型合併到此對應中，並保留已設定的無關提供者。
  • 對於直接 OpenAI Responses 模型，伺服器端壓縮會自動啟用。使用 params.responsesServerCompaction: false 可停止注入 context_management，或使用 params.responsesCompactThreshold 覆寫閾值。請參閱 OpenAI 伺服器端壓縮。
• params：套用至所有模型的全域預設提供者參數。設定於 agents.defaults.params（例如 { cacheRetention: "long" }）。
• params 合併優先順序（設定）：agents.defaults.params（全域基底）會被 agents.defaults.models["provider/model"].params（逐模型）覆寫，接著 agents.list[].params（符合的代理 ID）會依鍵覆寫。詳情請參閱 提示快取。
• models.providers.openrouter.params.provider：OpenRouter 全域預設提供者路由政策。OpenClaw 會將其轉發到 OpenRouter 的請求 provider 物件；逐模型的 agents.defaults.models["openrouter/<model>"].params.provider 和代理參數會依鍵覆寫。請參閱 OpenRouter 提供者路由。
• params.extra_body/params.extraBody：進階透傳 JSON，會合併到 OpenAI 相容代理的 api: "openai-completions" 請求主體中。如果它與產生的請求鍵衝突，額外主體會優先；非原生 completions 路由之後仍會移除 OpenAI 專用的 store。
• params.chat_template_kwargs：vLLM/OpenAI 相容的聊天範本引數，會合併到頂層 api: "openai-completions" 請求主體中。對於關閉 thinking 的 vllm/nemotron-3-*，內建 vLLM 外掛會自動傳送 enable_thinking: false 與 force_nonempty_content: true；明確的 chat_template_kwargs 會覆寫產生的預設值，而 extra_body.chat_template_kwargs 仍具有最終優先權。已設定的 vLLM Qwen 與 Nemotron thinking 模型會公開二元 /think 選項（off、on），而不是多層級的 effort 階梯。
• compat.thinkingFormat：OpenAI 相容的 thinking 酬載樣式。Together 樣式的 reasoning.enabled 使用 "together"，Qwen 樣式的頂層 enable_thinking 使用 "qwen"，或在支援請求層級聊天範本 kwargs 的 Qwen 系列後端（例如 vLLM）上，針對 chat_template_kwargs.enable_thinking 使用 "qwen-chat-template"。OpenClaw 會將停用的 thinking 對應為 false，將啟用的 thinking 對應為 true，且已設定的 vLLM Qwen 模型會針對這些格式公開二元 /think 選項。
• compat.supportedReasoningEfforts：逐模型的 OpenAI 相容推理 effort 清單。對於真正接受它的自訂端點，請包含 "xhigh"；OpenClaw 之後會在命令選單、閘道工作階段列、工作階段修補驗證、代理命令列介面驗證，以及該已設定提供者/模型的 llm-task 驗證中公開 /think xhigh。當後端需要標準層級的提供者特定值時，請使用 compat.reasoningEffortMap。
• params.preserveThinking：僅限 Z.AI 的保留 thinking 選用設定。啟用且 thinking 開啟時，OpenClaw 會傳送 thinking.clear_thinking: false 並重播先前的 reasoning_content；請參閱 Z.AI thinking 與保留 thinking。
• 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-8": {
          agentRuntime: { id: "claude-cli" },
        },
        "vllm/*": {
          agentRuntime: { id: "openclaw" },
        },
      },
    },
  },
}

• id: "auto"、"openclaw"、已註冊的外掛 harness id，或支援的命令列介面後端別名。內建的 Codex 外掛會註冊 codex；內建的 Anthropic 外掛提供 claude-cli 命令列介面後端。
• id: "auto" 會讓已註冊的外掛 harness 認領支援的回合，且在沒有 harness 符合時使用 OpenClaw。明確的外掛執行階段（例如 id: "codex"）需要該 harness，且若其不可用或失敗，會封閉失敗。
• id: "pi" 僅作為 openclaw 的已棄用別名被接受，用於保留 v2026.5.22 及更早版本已出貨的設定。新的設定應使用 openclaw。
• 執行階段優先順序會先採用精確模型政策（agents.list[].models["provider/model"]、agents.defaults.models["provider/model"] 或 models.providers.<provider>.models[]），接著是 agents.list[] / agents.defaults.models["provider/*"]，最後是 models.providers.<provider>.agentRuntime 的提供者範圍政策。
• 整個代理程式的執行階段鍵是舊版項目。agents.defaults.agentRuntime、agents.list[].agentRuntime、工作階段執行階段釘選，以及 OPENCLAW_AGENT_RUNTIME 都會被執行階段選擇忽略。執行 openclaw doctor --fix 以移除過期值。
• OpenAI 代理程式模型預設使用 Codex harness；當你想明確指定時，provider/model agentRuntime.id: "codex" 仍然有效。
• 對於 Claude 命令列介面部署，建議使用 model: "anthropic/claude-opus-4-8" 搭配模型範圍的 agentRuntime.id: "claude-cli"。舊版 claude-cli/<model> 參照為了相容性仍可運作，但新的設定應保持 provider/model 選擇為標準形式，並將執行後端放在 provider/model 執行階段政策中。
• 這只控制文字代理程式回合的執行。媒體生成、視覺、PDF、音樂、影片和 TTS 仍使用其 provider/model 設定。

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "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",
        },
      },
    },
  },
}

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

​

agents.defaults.promptOverlays

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

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

​

agents.defaults.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.md 注入 bootstrap 脈絡。預設：true。
• suppressToolErrorWarnings: 為 true 時，會在心跳偵測執行期間抑制工具錯誤警告酬載。
• timeoutSeconds: 心跳偵測代理程式回合被中止前允許的最長秒數。未設定時，若已設定則使用 agents.defaults.timeoutSeconds，否則使用心跳偵測節奏並上限為 600 秒。
• directPolicy: 直接/DM 傳遞政策。allow（預設）允許直接目標傳遞。block 會抑制直接目標傳遞並發出 reason=dm-blocked。
• lightContext: 為 true 時，心跳偵測執行會使用輕量 bootstrap 脈絡，且只保留工作區 bootstrap 檔案中的 HEARTBEAT.md。
• isolatedSession: 為 true 時，每次心跳偵測都會在沒有先前對話歷史的新工作階段中執行。與排程 sessionTarget: "isolated" 相同的隔離模式。將每次心跳偵測的 token 成本從約 100K 降至約 2-5K token。
• skipWhenBusy: 為 true 時，心跳偵測執行會在該代理程式的額外忙碌通道上延後：其自己的工作階段鍵控 subagent 或巢狀命令工作。排程通道一律會延後心跳偵測，即使沒有此旗標也是如此。
• 每個代理程式：設定 agents.list[].heartbeat。當任何代理程式定義 heartbeat 時，只有那些代理程式會執行心跳偵測。
• 心跳偵測會執行完整代理程式回合 — 較短的間隔會消耗更多 token。

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 180,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        recentTurnsPreserve: 3,
        maxHistoryShare: 0.7,
        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 tool-loop pressure check
        postIndexSync: "async", // off | async | await
        postCompactionSections: ["Session Startup", "Red Lines"], // opt in to AGENTS.md section 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, // notices when compaction starts/completes and on memory-flush degradation (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          forceFlushTranscriptBytes: "2mb",
          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（長歷史記錄的分塊摘要）。請參閱壓縮。
• provider：已註冊壓縮提供者外掛的 ID。設定後，會呼叫提供者的 summarize()，而不是內建 LLM 摘要。失敗時會退回內建機制。設定提供者會強制使用 mode: "safeguard"。請參閱壓縮。
• timeoutSeconds：OpenClaw 中止單次壓縮操作前允許的最長秒數。預設值：180。
• reserveTokens：壓縮後保留給模型輸出和未來工具結果的 token 餘量。當模型脈絡視窗已知時，OpenClaw 會限制有效保留量，使其無法耗盡提示預算。
• reserveTokensFloor：內嵌執行階段強制執行的最低保留量。設定為 0 可停用下限。此下限仍受作用中的脈絡視窗上限約束。
• keepRecentTokens：代理保留最近逐字記錄尾端的切點預算。手動 /compact 在明確設定時會遵守此值；否則手動壓縮會是硬性檢查點。
• recentTurnsPreserve：在 safeguard 摘要外逐字保留的最新使用者/助理回合數。預設值：3。
• maxHistoryShare：壓縮後保留歷史記錄可使用的總脈絡預算最大比例（範圍 0.1-0.9）。
• identifierPolicy：strict（預設）、off 或 custom。strict 會在壓縮摘要期間前置內建的不透明識別碼保留指引。
• identifierInstructions：當 identifierPolicy=custom 時使用的選用自訂識別碼保留文字。
• qualityGuard：針對 safeguard 摘要的格式錯誤輸出重試檢查。在 safeguard 模式中預設啟用；設定 enabled: false 可略過稽核。
• midTurnPrecheck：選用的工具迴圈壓力檢查。當 enabled: true 時，OpenClaw 會在附加工具結果後、下一次模型呼叫前檢查脈絡壓力。如果脈絡已無法容納，它會在提交提示前中止目前嘗試，並重用既有的預檢復原路徑來截斷工具結果或壓縮後重試。適用於 default 和 safeguard 兩種壓縮模式。預設：停用。
• postIndexSync：壓縮後的工作階段記憶重新索引模式。預設值："async"。若要最強的新鮮度，請使用 "await"；若要較低的壓縮延遲，請使用 "async"；只有在工作階段記憶同步由其他地方處理時，才使用 "off"。
• postCompactionSections：壓縮後要重新注入的選用 AGENTS.md H2/H3 區段名稱。未設定或設定為 [] 時會停用重新注入。明確設定 ["Session Startup", "Red Lines"] 會啟用該組合，並保留舊版 Every Session/Safety 備援。只有在額外脈絡值得承擔重複已在壓縮摘要中捕捉的專案指引風險時，才啟用此選項。
• model：僅用於壓縮摘要的選用 provider/model-id 或來自 agents.defaults.models 的裸別名。裸別名會在分派前解析；設定的字面模型 ID 在衝突時保留優先權。當主要工作階段應保留一個模型，但壓縮摘要應在另一個模型上執行時使用此設定；未設定時，壓縮會使用工作階段的主要模型。
• truncateAfterCompaction：在壓縮後輪替作用中工作階段 JSONL，使未來回合只載入摘要和未摘要尾端，同時先前的完整逐字記錄仍會封存。防止長時間執行工作階段中的作用中逐字記錄無限制成長。預設值：false。
• maxActiveTranscriptBytes：選用位元組閾值（number 或像 "20mb" 這樣的字串），當作用中 JSONL 增長超過閾值時，會在執行前觸發一般本機壓縮。需要 truncateAfterCompaction，使成功壓縮可輪替到較小的後續逐字記錄。未設定或為 0 時停用。
• notifyUser：當為 true 時，會向使用者傳送簡短的脈絡維護通知：壓縮開始與完成時（例如「正在壓縮脈絡…」和「壓縮完成」），以及壓縮前記憶清除已耗盡、因此回覆以降級狀態繼續時（例如「記憶維護暫時失敗；正在繼續你的回覆。」）。預設停用，以保持這些通知靜默。
• memoryFlush：自動壓縮前的靜默代理式回合，用於儲存持久記憶。當此維護回合應保留在本機模型上時，將 model 設為確切的提供者/模型，例如 ollama/qwen3:8b；此覆寫不會繼承作用中工作階段的備援鏈。forceFlushTranscriptBytes 會在逐字記錄檔案大小達到閾值時強制清除，即使 token 計數器已過時。工作區為唯讀時會略過。

​

agents.defaults.runRetries

{
  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

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off (default) | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes; default: 5m
        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, breakPreference: "paragraph" },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off (default) | natural | custom (use minMs/maxMs)
    },
  },
}

• 非 Telegram 頻道需要明確設定 *.blockStreaming: true 才能啟用區塊回覆。
• 頻道覆寫：channels.<channel>.blockStreamingCoalesce（以及每個帳號的變體）。Discord、Google Chat、Mattermost、MS Teams、Signal 和 Slack 預設為 minChars: 1500 / idleMs: 1000。
• blockStreamingChunk.breakPreference：偏好的分塊邊界（"paragraph" | "newline" | "sentence"）。
• humanDelay：區塊回覆之間的隨機暫停。預設值：off。natural = 800-2500ms。custom 使用 minMs/maxMs（任何未設定的邊界會退回自然範圍）。每個代理覆寫：agents.list[].humanDelay。

​

輸入指示器

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

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

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off (default) | non-main | all
        backend: "docker", // docker (default) | ssh | openshell
        scope: "agent", // session | agent (default) | shared
        workspaceAccess: "none", // none (default) | 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,
          gpus: "all",
          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 (default) | remote
          command: "openshell",
          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,
        },
      },
    },
  },
}

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

​

agents.list（每個代理覆寫）

{
  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 }
        utilityModel: "openai/gpt-5.4-mini",
        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: { speakerVoiceId: "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", // persistent | oneshot
            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 的排程工作仍會繼承預設後援，除非你設定 fallbacks: []。
• utilityModel：可選的每代理覆寫，用於產生工作階段與執行緒標題等短內部工作。會後援至 agents.defaults.utilityModel，再後援至此代理的主要模型。
• 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：可選的每代理快速模式預設值（"auto" | true | false）。在未設定每訊息或工作階段快速模式覆寫時套用。
• models：可選的每代理模型目錄/執行階段覆寫，以完整 provider/model id 作為鍵。使用 models["provider/model"].agentRuntime 設定每代理執行階段例外。
• runtime：可選的每代理執行階段描述符。當代理應預設使用 ACP 控制框架工作階段時，請使用 type: "acp" 搭配 runtime.acp 預設值（agent、backend、mode、cwd）。
• identity.avatar：工作區相對路徑、http(s) URL，或 data: URI。
• 本機工作區相對的 identity.avatar 圖片檔案限制為 2 MB。http(s) URL 和 data: URI 不會套用本機檔案大小限制檢查。
• identity 會衍生預設值：從 emoji 衍生 ackReaction，從 name/emoji 衍生 mentionPatterns。
• subagents.allowAgents：為明確的 sessions_spawn.agentId 目標設定已配置代理 id 的允許清單（["*"] = 任何已配置目標；預設：僅同一代理）。當應允許自我目標的 agentId 呼叫時，請包含請求者 id。若代理設定已刪除，過時項目會被 sessions_spawn 拒絕，並從 agents_list 省略；執行 openclaw doctor --fix 清理，或在該目標應於繼承預設值時仍可被產生的情況下，加入最小的 agents.list[] 項目。
• 沙箱繼承防護：若請求者工作階段已沙箱化，sessions_spawn 會拒絕將以非沙箱方式執行的目標。
• subagents.requireAgentId：為 true 時，封鎖省略 agentId 的 sessions_spawn 呼叫（強制明確選取設定檔；預設：false）。
• subagents.maxConcurrent：跨子代理執行的最大並行子代理執行數。預設值：8。
• subagents.maxChildrenPerAgent：單一代理工作階段可產生的最大作用中子項數。預設值：5。
• subagents.maxSpawnDepth：子代理產生的最大巢狀深度（1-5）。預設值：1（不巢狀）。
• subagents.archiveAfterMinutes：已完成子代理狀態封存前的存在時間。預設值：60。

​

多代理路由

{
  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. 預設代理

​

每代理存取設定檔

{
  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 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 30 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "enforce", // enforce (default) | warn
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    writeLock: {
      acquireTimeoutMs: 60000,
      staleMs: 1800000,
      maxHoldMs: 300000,
    },
    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: "🦞", // 或 "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all | off | none
    removeAckAfterReply: false,
    queue: {
      mode: "steer", // steer（預設）| followup | collect | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize（預設）
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 會停用
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

回覆前綴

​

確認反應

• 預設為作用中代理程式的 identity.emoji，否則為 "👀"。設為 "" 可停用。
• 按頻道覆寫：channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。
• 解析順序：帳號 → 頻道 → messages.ackReaction → 身分後援。
• 範圍：group-mentions（預設）、group-all、direct、all 或 off/none（完全停用確認反應）。
• removeAckAfterReply：在支援反應的頻道（例如 Slack、Discord、Signal、Telegram、WhatsApp 和 iMessage）上於回覆後移除確認。
• messages.statusReactions.enabled：在 Slack、Discord、Signal、Telegram 和 WhatsApp 上啟用生命週期狀態反應。 在 Discord 上，未設定時會在確認反應作用中時保持狀態反應啟用。 在 Slack、Signal、Telegram 和 WhatsApp 上，明確設為 true 才會啟用生命週期狀態反應。 Slack 預設使用其原生助理執行緒狀態和輪替載入訊息來表示進度，同時讓已設定的確認反應保持靜態。
• messages.statusReactions.emojis：覆寫生命週期表情符號鍵： queued、thinking、compacting、tool、coding、web、deploy、build、 concierge、done、error、stallSoft 和 stallHard。 Telegram 只允許固定的反應集合，因此不支援的已設定表情符號會退回 到該聊天最接近的受支援狀態變體。

​

佇列

• mode：工作階段執行作用中時，傳入訊息抵達的佇列策略。預設："steer"。
  • steer：將新的提示注入作用中執行。
  • followup：在作用中執行完成後執行新的提示。
  • collect：批次處理相容訊息，稍後一起執行。
  • interrupt：在開始最新提示前中止作用中執行。
• debounceMs：派送已佇列/已導向訊息前的延遲。預設：500。
• cap：套用丟棄政策前的最大已佇列訊息數。預設：20。
• drop：超過上限時的策略。"summarize"（預設）會丟棄最舊項目但保留壓縮摘要；"old" 會丟棄最舊項目且不保留摘要；"new" 會拒絕最新項目。
• byChannel：按頻道的 mode 覆寫，以提供者 ID 作為鍵。
• debounceMsByChannel：按頻道的 debounceMs 覆寫，以提供者 ID 作為鍵。

​

傳入防抖

​

其他訊息鍵

• messages.messagePrefix：在傳入使用者訊息到達代理程式執行階段之前加上的前綴文字。請謹慎用於頻道情境標記。
• messages.visibleReplies：控制 direct、group 和 channel 對話中的可見來源回覆（"message_tool" 需要 message(action=send) 才能產生可見輸出；"automatic" 會如同先前一樣張貼一般回覆）。
• messages.usageTemplate / messages.responseUsage：自訂 /usage 頁尾範本和預設逐回覆使用量模式（off | tokens | full，加上舊版 on 作為 tokens 的別名）。
• messages.groupChat.mentionPatterns / historyLimit：群組訊息提及觸發條件和歷史視窗大小。
• messages.suppressToolErrors：當為 true 時，抑制顯示給使用者的 ⚠️ 工具錯誤警告（代理程式仍會在情境中看到錯誤並可重試）。預設：false。

​

TTS（文字轉語音）

{
  messages: {
    tts: {
      auto: "off", // off（預設）| always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-5.4-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          speakerVoiceId: "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: {
          speakerVoice: "en-US-MichelleNeural",
          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",
          speakerVoice: "coral",
        },
      },
    },
  },
}

• auto 控制預設 auto-TTS 模式：off、always、inbound 或 tagged。/tts on|off 可以覆寫本機偏好設定，而 /tts status 會顯示有效狀態。
• summaryModel 會覆寫 agents.defaults.model.primary 以用於自動摘要。
• modelOverrides 預設啟用（enabled !== false）；modelOverrides.allowProvider 需選擇啟用。
• API 金鑰會退回使用 ELEVENLABS_API_KEY/XI_API_KEY 和 OPENAI_API_KEY。
• 內建語音提供者由外掛擁有。如果設定了 plugins.allow，請包含你要使用的每個 TTS 提供者外掛，例如 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: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_multilingual_v2",
        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",
          speakerVoice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime", // realtime | stt-tts | transcription
      transport: "webrtc", // webrtc | provider-websocket | gateway-relay | managed-room
      vadThreshold: 0.5,
      silenceDurationMs: 500,
      prefixPaddingMs: 300,
      reasoningEffort: "medium",
      brain: "agent-consult", // agent-consult | direct-tools | none
    },
  },
}

• 當設定多個 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（macOS Talk 用戶端行為）。
• providers.*.apiKey 接受純文字字串或 SecretRef 物件。
• ELEVENLABS_API_KEY 退回僅在未設定 Talk API 金鑰時套用。
• providers.*.voiceAliases 讓 Talk 指令可以使用友善名稱。
• providers.mlx.modelId 選取 macOS 本機 MLX 輔助程式使用的 Hugging Face repo。若省略，macOS 會使用 mlx-community/Soprano-80M-bf16。
• macOS MLX 播放會在存在時透過內建 openclaw-mlx-tts 輔助程式執行，或透過 PATH 上的可執行檔執行；OPENCLAW_MLX_TTS_BIN 會覆寫開發用的輔助程式路徑。
• consultThinkingLevel 控制 Control UI Talk 即時 openclaw_agent_consult 呼叫背後完整 OpenClaw agent 執行的思考層級。保留未設定可維持一般工作階段/模型行為。
• 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 指引。
• realtime.vadThreshold 設定提供者語音活動閾值，範圍從 0（最敏感）到 1（最不敏感）。未設定時會保留提供者預設值。
• realtime.silenceDurationMs 設定提供者提交即時使用者回合前的正整數靜默視窗。未設定時會保留提供者預設值。
• realtime.prefixPaddingMs 設定偵測到語音開始前保留的非負整數音訊量。未設定時會保留提供者預設值。
• realtime.reasoningEffort 設定即時工作階段的提供者特定推理層級。未設定時會保留提供者預設值。
• realtime.consultRouting："provider-direct"（預設）會在即時提供者產生不含 openclaw_agent_consult 的最終使用者逐字稿時，保留直接提供者回覆。"force-agent-consult" 會改由 OpenClaw 路由已定稿的請求。

​

相關

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