配置 — 代理

​

代理默认值

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skills

{
  agents: {
    ownership: "explicit",
    defaults: { skills: ["github", "weather"] },
    entries: {
      writer: {}, // inherits github, weather
      docs: { skills: ["docs-search"] }, // replaces defaults
      "locked-down": { skills: [] }, // no skills
    },
  },
}

• 默认情况下，省略 agents.defaults.skills 表示不限制技能。
• 省略 agents.entries.*.skills 表示继承默认值。
• 将 agents.entries.*.skills 设置为 [] 表示无技能。
• 非空的 agents.entries.*.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,
    },
    entries: {
      "strict-worker": {
        contextInjection: "always",
        bootstrapMaxChars: 50000,
        bootstrapTotalMaxChars: 300000,
      },
    },
  },
}

​

Bootstrap 截断通知

​

上下文预算所有权映射

• agents.entries.*.skillsLimits.maxSkillsPromptChars
• agents.entries.*.contextInjection
• agents.entries.*.bootstrapMaxChars
• agents.entries.*.bootstrapTotalMaxChars
• agents.entries.*.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,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars：截断前的默认 memory_get 摘录上限。 添加元数据和续接提示后，内容可能会进一步增加。
• 当 memory_get 未指定 lines 时，OpenClaw 使用内置的 120 行窗口， 然后应用 memoryGetMaxChars。
• 实时工具结果使用模型上下文自动上限：低于 100K 个 token 时为 16000 个字符， 达到 100K+ 个 token 时为 32000 个字符，达到 200K+ 个 token 时为 64000 个字符。
• postCompactionMaxChars：压缩后刷新注入期间所使用的 AGENTS.md 摘录上限。

​

agents.entries.*.contextLimits

{
  agents: {
    defaults: {
      contextLimits: { memoryGetMaxChars: 12000 },
    },
    entries: {
      "tiny-local": {
        contextLimits: {
          memoryGetMaxChars: 6000,
        },
      },
    },
  },
}

​

skills.limits.maxSkillsPromptChars

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

​

agents.entries.*.skillsLimits.maxSkillsPromptChars

{
  agents: {
    entries: {
      "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.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"],
      },
      mediaModels: {
        image: {
          primary: "openai/gpt-image-2",
          fallbacks: ["google/gemini-3.1-flash-image"],
        },
        video: {
          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" }, // 全局默认提供商参数
      pdfMaxMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      fastModeDefault: false,
      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 私聊主题标题、Discord 自动线程标题，以及进度草稿旁白。未设置时，如果主提供商声明了小模型默认值，OpenClaw 会使用该默认值（OpenAI → gpt-5.6-luna，Anthropic → claude-haiku-4-5）；否则标题任务使用代理的主模型，旁白保持关闭。如果独立的 utility 模型无法准备或完成生成的标题，OpenClaw 会使用主模型重试该标题一次。对于仪表板标题，自动 utility 推导和常规回退会使用有效会话提供商和身份验证配置文件；显式设置的 utility 模型则保留其配置的提供商／身份验证。设置 utilityModel: "" 可跳过备用 utility 路由；仪表板标题生成仍会直接使用常规会话模型继续进行。agents.entries.*.utilityModel 会覆盖默认值，而特定操作的模型覆盖项优先级高于两者。Utility 任务会单独调用模型，并将特定于任务的内容发送给所选模型提供商。仪表板标题生成最多发送第一条非命令消息的前 1,000 个字符；旁白会发送入站请求以及经过精简和脱敏的工具摘要。请选择符合成本和数据处理要求的提供商。
• imageModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
  • 当活动模型无法接受图像时，image 工具路径会将其视觉模型配置用于图像处理。原生视觉模型则会直接接收已加载的图像字节。
  • 当所选／默认模型无法接受图像输入时，也会用作回退路由。
  • 优先使用显式的 provider/model 引用。为兼容性也接受不带提供商的 ID；如果某个不带提供商的 ID 在 models.providers.*.models 中唯一匹配已配置的图像能力条目，OpenClaw 会将其限定到对应提供商。对于多个已配置匹配项，必须显式添加提供商前缀。
• mediaModels.image：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
  • 由共享的图像生成能力以及未来任何生成图像的工具／插件界面使用。
  • 典型值包括：用于原生 Gemini 图像生成的 google/gemini-3.1-flash-image，用于 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 顺序尝试其余已注册的图像生成提供商。
• mediaModels.music：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
  • 由共享的音乐生成能力和内置的 music_generate 工具使用。
  • 典型值包括：google/lyria-3-clip-preview、google/lyria-3-pro-preview 或 minimax/music-2.6。
  • 如果省略，music_generate 仍可推断出具有身份验证支持的提供商默认值。它会首先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。
  • 如果直接选择提供商／模型，也请配置匹配的提供商身份验证／API 密钥。
• mediaModels.video：接受字符串（"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，然后回退到已解析的会话／默认模型。
• pdfMaxMb：当调用时未传入 maxBytesMb，pdf 工具使用的默认 PDF 大小限制。
• pdfMaxPages：pdf 工具在提取回退模式下考虑的默认最大页数。
• fastModeDefault：代理的默认快速模式。取值："auto"、true、false。当未设置每条消息或会话级快速模式覆盖项时，每个代理的 agents.entries.*.fastModeDefault 会覆盖此设置。
• verboseDefault：代理的默认详细程度。取值："off"、"on"、"full"。默认值："off"。
• toolProgressDetail：/verbose 工具摘要和进度草稿工具行的详细程度模式。取值："explain"（默认，简洁的人类可读标签）或 "raw"（如果可用，则附加原始命令／详细信息）。每个代理的 agents.entries.*.toolProgressDetail 会覆盖此默认值。
• reasoningDefault：代理的默认推理可见性。取值："off"、"on"、"stream"。每个代理的 agents.entries.*.reasoningDefault 会覆盖此默认值。当未设置每条消息或会话级推理覆盖项时，配置的推理默认值仅会应用于所有者、已授权发送者或操作员管理员网关上下文。
• elevatedDefault：代理的默认提升输出级别。取值："off"、"on"、"ask"、"full"。默认值："on"。
• model.primary：格式为 provider/model（例如，用于 Codex OAuth 访问的 openai/gpt-5.6-sol）。如果省略提供商，OpenClaw 会依次尝试别名、与该确切模型 ID 匹配的唯一已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议使用显式的 provider/model）。如果该提供商不再提供已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商／模型，而不是暴露一个已过时的已移除提供商默认值。
• contextTokens：可选的代理级上限。它可以降低更大模型的有效预算，但无法将模型上限提高到其已配置或发现的 contextTokens 以上。若要让某个直接使用的 OpenAI 模型采用其更大的原生窗口，请为该模型设置 models.providers.openai.models[].contextWindow 和 contextTokens；请参阅 OpenAI 上下文窗口默认值。
• models：已配置的别名和每个模型的设置。每个条目可包含 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 会拒绝删除现有条目的替换操作。
• modelPolicy.allow：显式覆盖允许列表。接受别名、确切的 provider/model 引用，以及尾部前缀通配符，例如 openai/* 或 clawrouter/anthropic/*。省略它或使用 [] 可允许任何模型。agents.entries.*.modelPolicy.allow 会替换该代理的默认策略；显式的空列表会让该代理允许任何模型。
  • 按提供商限定的配置／引导流程会将所选提供商的模型合并到此映射中，并保留此前已配置的不相关提供商。
  • 对于直接使用的 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.entries.*.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" 请求体中。对于关闭思考的 vllm/nemotron-3-*，内置 vLLM 插件会自动发送 enable_thinking: false 和 force_nonempty_content: true；显式的 chat_template_kwargs 会覆盖生成的默认值，而 extra_body.chat_template_kwargs 仍具有最终优先级。已配置的 vLLM Qwen 和 Nemotron 思考模型会公开二进制的 /think 选项（off、on），而不是多级努力程度阶梯。
• compat.thinkingFormat：OpenAI 兼容的思考负载样式。对于 Together 风格的 reasoning.enabled，使用 "together"；对于 Qwen 风格顶层 enable_thinking，使用 "qwen"；对于支持请求级聊天模板参数的 Qwen 系列后端（例如 vLLM）中的 chat_template_kwargs.enable_thinking，使用 "qwen-chat-template"。OpenClaw 会将禁用思考映射为 false，将启用思考映射为 true；已配置的 vLLM Qwen 模型会为这些格式公开二进制 /think 选项。
• 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.entries.*.models["provider/model"].agentRuntime。仅使用提供商／模型前缀不会选择运行框架。当运行时未设置或为 auto 时，只有在确切的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由中，且没有编写请求覆盖项时，OpenAI 才可能隐式选择 Codex。请参阅 OpenAI 隐式代理运行时。
• 修改这些字段的配置写入器（例如 /models set、/models set-image 以及添加／移除回退模型的命令）会保存规范对象形式，并在可能的情况下保留现有的回退列表。
• maxConcurrent：跨会话的最大并行代理运行数（每个会话仍会串行执行）。默认情况下，OpenClaw 使用 min(16, max(8, available CPU parallelism))；该值基于 os.availableParallelism()，并在不可用时回退到 os.cpus().length。

​

运行时策略

{
  models: {
    providers: {
      openai: {
        agentRuntime: { id: "codex" },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.6-sol",
      models: {
        "anthropic/claude-opus-5": {
          agentRuntime: { id: "claude-cli" },
        },
        "vllm/*": {
          agentRuntime: { id: "openclaw" },
        },
      },
    },
  },
}

• id："auto"、"openclaw"、已注册的插件 harness id，或受支持的 CLI 后端别名。内置的 Codex 插件注册了 codex；内置的 Anthropic 插件提供了 claude-cli CLI 后端。
• id: "auto" 会让已注册的插件 harness 认领声明了其支持契约或以其他方式满足该契约的有效路由；如果没有 harness 匹配，则使用 OpenClaw。显式指定插件运行时（例如 id: "codex"）时，必须使用该 harness 和兼容的有效路由；如果任一项不可用或执行失败，则直接失败。
• id: "pi" 仅作为 openclaw 的弃用别名接受，用于保留 v2026.5.22 及更早版本中已发布的配置。新配置应使用 openclaw。
• 运行时优先级依次为：精确模型策略（agents.entries.*.models["provider/model"]、agents.defaults.models["provider/model"] 或 models.providers.<provider>.models[]），然后是 agents.entries.* / agents.defaults.models["provider/*"]，最后是 provider 范围的策略 models.providers.<provider>.agentRuntime。
• 整个 agent 级别的运行时键已弃用。运行时选择会忽略 agents.defaults.agentRuntime、agents.entries.*.agentRuntime、会话运行时固定值以及 OPENCLAW_AGENT_RUNTIME。运行 openclaw doctor --fix 可移除过时值。
• 符合条件的精确官方 HTTPS OpenAI Responses/ChatGPT 路由，在没有人为设置请求覆盖的情况下，可以隐式使用 Codex harness。将 provider/model 的 agentRuntime.id 设为 "codex" 会使 Codex 成为失败即终止的要求，但不会使不兼容的路由变得兼容。
• 对于 Claude CLI 部署，建议使用 model: "anthropic/claude-opus-5"，并配合模型范围的 agentRuntime.id: "claude-cli"。为兼容性起见，旧版的 claude-cli/<model> 引用仍可使用，但新配置应保持规范的 provider/model 选择，并将执行后端放入 provider/model 运行时策略中。
• 这只控制文本 agent 回合的执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider/model 设置。

​

CLI 后端选择

​

OpenAI GPT-5 个性

{
  plugins: {
    entries: {
      openai: {
        config: {
          personality: "friendly", // friendly | on | off
        },
      },
    },
  },
}

• "friendly"（默认）和"on"启用友好交互风格层。
• "off"仅禁用友好层；带标签的 GPT-5 行为契约仍保持启用状态。

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        agentId: "ops", // 未配置单个代理心跳时的环境所有者
        every: "30m", // 0m 表示禁用
        activeHours: { start: "08:00", end: "24:00" },
        model: "openai/gpt-5.4-mini",
        session: "main",
        target: "owner", // default | options: last | none | whatsapp | telegram | discord | ...
        directPolicy: "allow", // allow (default) | block
        to: "+15555550123",
        accountId: "ops-bot",
        prompt: "Follow the heartbeat monitor scratch context...",
        timeoutSeconds: 45,
        lightContext: false, // 默认值：false；为 true 时跳过心跳运行的工作区引导文件
        isolatedSession: false, // 默认值：false；为 true 时每次心跳都在全新会话中运行（无对话历史）
      },
    },
  },
}

• every：时长字符串（ms/s/m/h）。默认值：30m（API 密钥身份验证）或 1h（OAuth 身份验证）。设置为 0m 可禁用。
• agentId：当不存在 agents.entries.*.heartbeat 块时，用于环境心跳运行的显式所有者。没有 agentId 的共享心跳块会保留现有的全代理注册行为。
• 调度周期会写入系统拥有的 cron 监控行。运行 openclaw doctor --fix 可具体化缺失或过时的行。如果 cron 被禁用，计划心跳不会运行，网关会记录启动警告。
• 心跳对象是严格的。其支持的字段包括 every、activeHours、model、session、target、directPolicy、to、accountId、prompt、timeoutSeconds、lightContext 和 isolatedSession。
• timeoutSeconds：心跳代理回合在中止前允许的最长秒数。留空时，如果已设置，则使用 agents.defaults.timeoutSeconds；否则使用上限为 600 秒的心跳周期。
• directPolicy：直接消息／私聊投递策略。allow（默认值）允许直接目标投递。block 会抑制直接目标投递，并发出 reason=dm-blocked。
• target：owner（默认值）仅发送到来自 commands.ownerAllowFrom 或通道 allowFrom 的直接消息身份。last 显式跟随最新对话，包括群组。none 保持结果为内部结果。
• to：仅与显式通道目标一起使用。owner 和未设置的目标会忽略它。
• lightContext：为 true 时，心跳运行使用轻量级引导上下文并跳过工作区引导文件。无论如何，监控临时文件都会由心跳运行器注入。
• isolatedSession：为 true 时，每次心跳都会在没有此前对话历史的新会话中运行。其隔离模式与 cron 的 sessionTarget: "isolated" 相同。每次心跳的 token 成本会从约 100K 降低至约 2-5K。
• 忙碌延迟会自动执行：计划心跳会等待主任务／cron 活动、同一代理的活动运行以及目标会话工作完成；即时和手动唤醒仅会绕过广义的同一代理活动运行预检查。
• 只要某个已注册代理的周期启用，该代理的 Heartbeats 系统提示词部分就会自动包含在内。确认抑制使用固定的 300 字符剩余预算，推理负载仍保持内部状态，工具错误警告仍保持启用。
• 按代理设置：设置 agents.entries.*.heartbeat。只要有任意代理定义了 heartbeat，就只有这些代理运行心跳。
• 心跳会运行完整的代理回合——更短的间隔会消耗更多 token。

​

agents.defaults.systemAgent

{
  agents: {
    defaults: {
      systemAgent: { agentId: "ops" },
    },
  },
}

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        enabled: false, // 禁用嵌入式主动自动压缩（默认：true）
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // 已注册的压缩提供程序插件的 ID（可选）
        thinkingLevel: "low", // 仅用于压缩的可选思考级别覆盖
        timeoutSeconds: 180,
        keepRecentTokens: 50000,
        recentTurnsPreserve: 3,
        identifierPolicy: "strict", // strict | off
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // 可选的工具循环压力检查
        postIndexSync: "async", // off | async | await
        postCompactionSections: ["Session Startup", "Red Lines"],
        model: "openrouter/anthropic/claude-sonnet-4-6", // 可选的仅用于压缩的模型覆盖
        maxActiveTranscriptBytes: "20mb", // 启用压缩前本地预检
        notifyUser: true, // 压缩开始/完成以及 memory-flush 降级时发送通知（默认：false）
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // 可选的仅用于 memory-flush 的模型覆盖
          softThresholdTokens: 6000,
          forceFlushTranscriptBytes: "2mb",
        },
      },
    },
  },
}

• enabled：当为 false 时，禁用嵌入式代理运行时中由阈值驱动的自动压缩。OpenClaw 的预检和溢出恢复压缩路径，以及手动执行的 /compact 仍然可用。默认值：true。
• mode：default 或 safeguard（针对长历史记录的分块摘要）。参见 压缩。
• provider：已注册的压缩提供程序插件的 ID。设置后，将调用该提供程序的 summarize()，而不是使用内置的 LLM 摘要功能。失败时回退到内置实现。设置提供程序会强制使用 mode: "safeguard"。参见 压缩。
• thinkingLevel：仅用于嵌入式 OpenClaw 压缩摘要的可选思考级别（off、minimal、low、medium、high、xhigh、adaptive、max 或 ultra）。它会覆盖会话当前的思考级别，并根据所选压缩模型/运行时进行限制。未设置时继承会话级别。原生 Codex app-server 压缩会忽略此设置，因为原生压缩请求不支持按操作设置思考级别；配置此项时，OpenClaw 会记录警告。
• timeoutSeconds：单次压缩操作允许的最大秒数，超过后 OpenClaw 将中止该操作。默认值：180。
• keepRecentTokens：代理截断点预算，用于逐字保留最近的 transcript 尾部。默认值：20000。
• recentTurnsPreserve：在 safeguard 摘要之外逐字保留的最近用户/助手轮数。默认值：3。
• identifierPolicy：strict（默认）或 off。strict 会在压缩摘要过程中加入内置的不透明标识符保留指导。
• qualityGuard：针对 safeguard 摘要的格式错误输出进行重试检查。默认在 safeguard 模式下启用；设置 enabled: false 可跳过审核。
• midTurnPrecheck：可选的工具循环压力检查。当 enabled: true 时，OpenClaw 会在追加工具结果后、下一次模型调用前检查上下文压力。如果上下文不再适配，它会在提交提示词前中止当前尝试，并复用现有的预检恢复路径来截断工具结果或执行压缩后重试。default 和 safeguard 两种压缩模式均支持。默认：禁用。
• postIndexSync：压缩后的会话记忆重新索引模式。默认值："async"。使用 "await" 可获得最强的新鲜度，使用 "async" 可降低压缩延迟；仅当会话记忆同步由其他方式处理时才使用 "off"。
• postCompactionSections：可选的 AGENTS.md H2/H3 节名称，用于在压缩后重新注入。未设置或使用 [] 可禁用。
• model：可选的 provider/model-id 或来自 agents.defaults.models 的裸别名，仅用于压缩摘要。裸别名会在调度前解析；发生冲突时，已配置的字面模型 ID 优先。当主会话应继续使用一个模型、而压缩摘要应使用另一个模型时，可以使用此项；未设置时，压缩使用会话的主模型。
• maxActiveTranscriptBytes：字节阈值（可以是 number，或类似 "20mb" 的字符串），用于选择在运行前执行常规本地压缩，当 transcript 历史记录达到该阈值时生效。对于 Codex app-server 会话，相同阈值会限制原生 rollout transcript，过大的原生线程将重新开始。未设置或为 0 时禁用。当上下文引擎返回明确的压缩后继身份时，OpenClaw 会采用该身份；内置 SQLite 压缩器则保留当前身份。
• notifyUser：当为 true 时，会向用户发送简短的上下文维护通知：压缩开始和完成时（例如“正在压缩上下文……”和“压缩完成”），以及压缩前的 memory flush 耗尽、回复将在降级状态下继续时（例如“内存维护暂时失败；继续回复。”）。默认禁用，以保持这些通知静默。
• memoryFlush：自动压缩前执行的静默代理操作轮次，用于存储持久记忆。当该维护轮次应保持使用本地模型时，将 model 设置为确切的提供程序/模型，例如 ollama/qwen3:8b；该覆盖不会继承活动会话的回退链。即使 token 计数器已过时，当 transcript 大小达到阈值时，forceFlushTranscriptBytes 也会强制执行 flush。工作区为只读时会跳过。

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // 关闭（默认） | cache-ttl
      },
    },
  },
}

​

块流式输出

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // 开启 | 关闭
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200, breakPreference: "paragraph" },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // 关闭（默认） | 自然 | 自定义（使用 minMs/maxMs）
    },
  },
}

• 非 Telegram 渠道需要显式设置 *.streaming.block.enabled: true 才能启用分块回复。QQ Bot 是例外：它没有 streaming.block 相关键，并且只要 channels.qqbot.streaming.mode 不为 "off"，就会进行分块回复。
• 渠道覆盖项：channels.<channel>.streaming.block.coalesce（以及各账户对应的配置）。Discord、Google Chat、Mattermost、MS Teams、Signal 和 Slack 默认使用 minChars: 1500 / idleMs: 1000。
• blockStreamingChunk.breakPreference：首选的分块边界（"paragraph" | "newline" | "sentence"）。
• humanDelay：分块回复之间的随机暂停时间。默认值：off。natural = 800-2500 毫秒。custom 使用 minMs/maxMs（任一边界未设置时，将回退到自然范围）。代理级别的覆盖项：agents.entries.*.humanDelay。

​

输入指示器

{
  agents: {
    defaults: {
      typingMode: "instant", // 从不 | 立即 | 思考 | 消息
      typingIntervalSeconds: 6,
    },
  },
}

• 默认值：直接聊天/提及时为 instant，未提及的群聊中为 message。
• typingIntervalSeconds 默认值：6。
• 按代理覆盖：agents.entries.*.typingMode。

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off（默认）| non-main | all
        backend: "docker", // docker（默认）| podman | openshell | ssh
        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,
          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",
          // 也支持 SecretRef / 内联内容：
          // 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,
          noVncEnabled: 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
          command: "openshell",
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // 可选
          gatewayEndpoint: "https://lab.example", // 可选
          policy: "strict", // 可选 OpenShell 策略 ID
          providers: ["openai"], // 可选
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # 主沙箱镜像
scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像

​

agents.entries（每个代理的覆盖设置）

{
  agents: {
    entries: {
      main: {
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks }
        utilityModel: "openai/gpt-5.4-mini",
        thinkingDefault: "high", // 每个代理的 thinking 级别覆盖
        reasoningDefault: "on", // 每个代理的 reasoning 可见性覆盖
        fastModeDefault: false, // 每个代理的快速模式覆盖
        params: { cacheRetention: "none" }, // 按键覆盖 agents.defaults.models 中匹配的默认项 params
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // 设置后替换 agents.defaults.skills
        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 },
        },
      },
    },
  },
}

• agents.entries 对象键是稳定的代理 ID。
• default 已废弃。只有一个已配置的代理时，该代理会被隐式解析；多代理操作需要绑定、明确的 agentId 目标、作用域化的会话/存储所有者，或显式的 --agent/请求字段。
• model：字符串形式会为代理设置严格的主模型，不使用模型回退；对象形式的 { primary } 同样严格，除非添加 fallbacks。使用 { primary, fallbacks: [...] } 可让该代理启用回退，或使用 { primary, fallbacks: [] } 明确指定严格行为。只覆盖 primary 的 Cron 作业仍会继承默认回退，除非设置 fallbacks: []。
• utilityModel：可选的代理级覆盖项，用于生成会话标题和线程标题等简短内部任务。会回退到 agents.defaults.utilityModel，然后回退到当前有效会话提供程序声明的小模型默认值。控制面板标题会使用当前有效的常规会话模型重试一次。空字符串会跳过该代理的备用实用模型路径，但不会禁用控制面板标题生成。
• params：合并到 agents.defaults.models 中所选模型条目之上的代理级流参数。可使用它设置代理专用的覆盖项，例如 cacheRetention、temperature 或 maxTokens，而无需复制整个模型目录。
• tts：可选的代理级文本转语音覆盖项。该配置块会与 tts 深度合并，因此应将共享的提供程序凭据和回退策略保留在 tts 中，并仅在此处设置角色专用的值，例如提供程序、语音、模型、风格或自动模式。
• skills：可选的代理级技能允许列表。如果省略，代理会在设置时继承 agents.defaults.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：可选的代理级默认 reasoning 可见性（on | off | stream）。当未设置每条消息或会话级 reasoning 覆盖时，会覆盖该代理的 agents.defaults.reasoningDefault。
• fastModeDefault：可选的代理级快速模式默认值（"auto" | true | false）。当未设置每条消息或会话级快速模式覆盖时，会覆盖该代理的 agents.defaults.fastModeDefault。
• models：可选的代理级模型目录/运行时覆盖项，以完整的 provider/model ID 为键。使用 models["provider/model"].agentRuntime 设置代理级运行时例外。
• runtime：可选的代理级运行时描述符。当代理应默认使用 ACP harness 会话时，使用 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.entries.* 条目，使该目标在继承默认值的同时仍可生成。
• 沙箱继承保护：如果请求方会话处于沙箱中，sessions_spawn 会拒绝将以未沙箱方式运行的目标。
• subagents.requireAgentId：为 true 时，阻止省略 agentId 的 sessions_spawn 调用（强制显式选择配置；默认值：false）。
• subagents.maxConcurrent：子代理执行期间允许的最大并发子代理运行数。默认值：8。
• subagents.maxChildrenPerAgent：单个代理会话可以生成的最大活动子代理数。默认值：5。
• subagents.maxSpawnDepth：子代理生成的最大嵌套深度（1-5）。默认值：1（不嵌套）。
• subagents.archiveAfterMinutes：已完成子代理状态被归档前的存留时间。默认值：60。

​

多代理路由

{
  agents: {
    ownership: "explicit",
    defaults: { heartbeat: { agentId: "home" }, systemAgent: { agentId: "home" } },
    entries: {
      home: { workspace: "~/.openclaw/workspace-home" },
      work: { workspace: "~/.openclaw/workspace-work" },
    },
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
  talk: { agentId: "home" },
}

​

绑定匹配字段

• type（可选）：正常路由使用 route（缺省时默认为 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: {
    entries: {
      personal: {
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    },
  },
}

{
  agents: {
    entries: {
      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: {
    entries: {
      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", // 主 | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // 每日 | 空闲
      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（默认） | warn
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // 持续时间或 false
      maxDiskBytes: "500mb", // 可选的硬性预算
      highWaterBytes: "400mb", // 可选的清理目标
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // 默认空闲自动取消聚焦（小时）（`0` 禁用）
      maxAgeHours: 0, // 默认硬性最大时长（小时）（`0` 禁用）
    },
    sharing: {
      readOnly: true,
      suggest: true,
      drafts: true,
    },
    mainKey: "main", // 旧版（运行时始终使用 "main"）
    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
    queue: {
      mode: "steer", // steer (default) | followup | collect | interrupt
      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（完全禁用确认反应）。
• group-mentions 会确认提及代理的群组消息，包括设置了 requireMention: false 的群组。使用 group-all 可确认每条群组消息。
• messages.statusReactions.enabled：启用 Slack、Discord、Signal、Telegram 和 WhatsApp 上的生命周期状态反应。 在 Discord 上，未设置时，只要确认反应处于启用状态，状态反应就会保持启用。 在 Slack、Signal、Telegram 和 WhatsApp 上，必须明确设置为 true 才能启用生命周期状态反应。 默认情况下，Slack 使用其原生助手线程状态和轮换显示的加载消息来报告进度，同时保持配置的确认反应不变。

​

队列

• mode：在会话运行处于活动状态时到达的传入消息所使用的队列策略。默认值："steer"。
  • steer：将新提示注入活动运行中。
  • followup：在活动运行完成后运行新提示。
  • collect：批量收集兼容的消息，稍后一起运行。
  • interrupt：在启动最新提示前中止活动运行。
• 队列对 steer、followup 和 collect 批处理使用内置的 500 毫秒去抖。
• cap：在应用丢弃策略前排队消息的最大数量。默认值：20。
• drop：超过上限时使用的策略。"summarize"（默认）会丢弃最旧的条目，但保留简要摘要；"old" 会丢弃最旧的条目且不保留摘要；"new" 会拒绝最新的条目。
• byChannel：按提供方 ID 设置的各频道 mode 覆盖值。
• debounceMsByChannel：按提供方 ID 设置的各频道去抖覆盖值，单位为毫秒。

​

传入去抖

​

其他消息键

• channels.whatsapp.responsePrefix：出站 WhatsApp 回复前缀。仅当规范值未设置时，Doctor 才会将已弃用的入站 messagePrefix 值移至此处。
• messages.visibleReplies：控制直接、群组和频道会话中可见的源回复（"message_tool" 要求使用 message(action=send) 才能产生可见输出；"automatic" 则像以前一样发布普通回复）。
• messages.usageTemplate / messages.responseUsage：自定义 /usage 页脚模板和每次回复的默认用量模式（off | tokens | full，以及作为 tokens 别名的旧版 on）。
• messages.groupChat.mentionPatterns / historyLimit：群组消息提及触发模式和历史记录窗口大小。
• messages.suppressToolErrors：为 true 时，隐藏向用户显示的 ⚠️ 工具错误警告（代理仍会在上下文中看到错误并可以重试）。默认：false。

​

TTS（文本转语音）

{
  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,
    providers: {
      elevenlabs: {
        apiKey: "example-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: "example-openai-api-key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        speakerVoice: "coral",
      },
    },
  },
}

• 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: {
    agentId: "ops",
    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.1",
          speakerVoice: "cedar",
        },
      },
      instructions: "温和地说话，并保持回答简短。",
      mode: "realtime", // 实时 | 语音转文本-文本转语音 | 转录
      transport: "webrtc", // webrtc | 提供商 WebSocket | 网关中继 | 托管房间
      vadThreshold: 0.5,
      silenceDurationMs: 500,
      prefixPaddingMs: 300,
      reasoningEffort: "medium",
      brain: "agent-consult", // agent-consult | 直接工具 | 无
    },
  },
}

• 当配置了多个语音对话提供商时，talk.provider 必须与 talk.providers 中的某个键匹配。
• 对于未指定代理作用域会话密钥而创建的语音对话会话，talk.agentId 负责管理这些会话。会话作用域的语音对话调用仍会使用该密钥中编码的代理。对于现有的多代理配置，Doctor 可能会创建一个仅包含此所有者的最小 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 语音对话客户端行为）。
• providers.*.apiKey 接受纯文本字符串或 SecretRef 对象。
• 仅当未配置语音对话 API 密钥时，才会应用 ELEVENLABS_API_KEY 回退值。
• providers.*.voiceAliases 允许语音对话指令使用易记名称。
• providers.mlx.modelId 选择 macOS 本地 MLX 辅助程序所使用的 Hugging Face 仓库。如果省略，macOS 将使用 mlx-community/Soprano-80M-bf16。
• macOS MLX 播放会在可用时通过捆绑的 openclaw-mlx-tts 辅助程序运行，否则使用 PATH 上的可执行文件；OPENCLAW_MLX_TTS_BIN 可在开发过程中覆盖辅助程序路径。
• consultThinkingLevel 控制控制界面语音对话实时 openclaw_agent_consult 调用背后完整 OpenClaw 代理运行时的思考级别。不设置则保持正常的会话/模型行为。
• consultFastMode 为控制界面语音对话实时咨询设置一次性的快速模式覆盖，不会更改会话的正常快速模式设置。
• speechLocale 设置由 Android、iOS 和 macOS 语音对话语音识别以及 iOS 系统语音回退所使用的 BCP 47 区域设置 ID。Android 还会使用其中的语言组件来辅助实时输入转录。不设置则使用设备默认值。
• silenceTimeoutMs 控制语音对话模式在用户静音后等待多长时间再发送转录文本。不设置则保留平台默认的暂停时间窗口（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 处理。

​

相关

• 配置参考 — 其他所有配置键
• 配置 — 常见任务和快速设置
• 配置示例。