配置 — 代理

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

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

​

代理默认值

​

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: [] }, // 无技能
    ],
  },
}

• 默认情况下省略 agents.defaults.skills，则不限制技能。
• 省略 agents.list[].skills 可继承默认值。
• 将 agents.list[].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: 12000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

• "off"：从不将警告文本注入系统提示词。
• "once"：按每个唯一的截断签名注入一次警告（推荐）。
• "always"：只要存在截断，就在每次运行时注入警告。

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

​

上下文预算所有权映射

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars： 正常的工作区引导注入。
• agents.defaults.startupContext.*： 一次性的重置/启动模型运行前奏，包括最近的每日 memory/*.md 文件。裸聊天 /new 和 /reset 命令会被确认，但不会调用模型。
• skills.limits.*： 注入系统提示词中的紧凑技能列表。
• agents.defaults.contextLimits.*： 有边界的运行时摘录和注入的运行时拥有块。
• memory.qmd.limits.*： 索引化的记忆搜索片段和注入大小。

• agents.list[].skillsLimits.maxSkillsPromptChars
• 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,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars：memory_get 摘录在添加截断元数据和续接提示前的默认上限。
• memoryGetDefaultLines：省略 lines 时，memory_get 的默认行窗口。
• toolResultMaxChars：用于持久化结果和溢出恢复的实时工具结果上限。
• postCompactionMaxChars：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    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.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"],
      },
      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" }, // 全局默认提供方参数
      agentRuntime: {
        id: "pi", // pi | auto | registered harness id, e.g. codex
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
  • String form sets only the primary model.
  • Object form sets primary plus ordered failover models.
• imageModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
  • Used by the image tool path as its vision-model config.
  • Also used as fallback routing when the selected/default model cannot accept image input.
  • Prefer explicit provider/model refs. Bare IDs are accepted for compatibility; if a bare ID uniquely matches a configured image-capable entry in models.providers.*.models, OpenClaw qualifies it to that provider. Ambiguous configured matches require an explicit provider prefix.
• imageGenerationModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
  • Used by the shared image-generation capability and any future tool/plugin surface that generates images.
  • Typical values: google/gemini-3.1-flash-image-preview for native Gemini image generation, fal/fal-ai/flux/dev for fal, openai/gpt-image-2 for OpenAI Images, or openai/gpt-image-1.5 for transparent-background OpenAI PNG/WebP output.
  • If you select a provider/model directly, configure matching provider auth too (for example GEMINI_API_KEY or GOOGLE_API_KEY for google/*, OPENAI_API_KEY or OpenAI Codex OAuth for openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY for fal/*).
  • If omitted, image_generate can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered image-generation providers in provider-id order.
• musicGenerationModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
  • Used by the shared music-generation capability and the built-in music_generate tool.
  • Typical values: google/lyria-3-clip-preview, google/lyria-3-pro-preview, or minimax/music-2.6.
  • If omitted, music_generate can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered music-generation providers in provider-id order.
  • If you select a provider/model directly, configure the matching provider auth/API key too.
• videoGenerationModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
  • Used by the shared video-generation capability and the built-in video_generate tool.
  • Typical values: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash, or qwen/wan2.7-r2v.
  • If omitted, video_generate can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered video-generation providers in provider-id order.
  • If you select a provider/model directly, configure the matching provider auth/API key too.
  • The bundled Qwen video-generation provider supports up to 1 output video, 1 input image, 4 input videos, 10 seconds duration, and provider-level size, aspectRatio, resolution, audio, and watermark options.
• pdfModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
  • Used by the pdf tool for model routing.
  • If omitted, the PDF tool falls back to imageModel, then to the resolved session/default model.
• pdfMaxBytesMb: default PDF size limit for the pdf tool when maxBytesMb is not passed at call time.
• pdfMaxPages: default maximum pages considered by extraction fallback mode in the pdf tool.
• verboseDefault: default verbose level for agents. Values: "off", "on", "full". Default: "off".
• reasoningDefault: default reasoning visibility for agents. Values: "off", "on", "stream". Per-agent agents.list[].reasoningDefault overrides this default. Configured reasoning defaults are only applied for owners, authorized senders, or operator-admin gateway contexts when no per-message or session reasoning override is set.
• elevatedDefault: default elevated-output level for agents. Values: "off", "on", "ask", "full". Default: "on".
• model.primary: format provider/model (e.g. openai/gpt-5.5 for API-key access or openai-codex/gpt-5.5 for Codex OAuth). If you omit the provider, OpenClaw tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider (deprecated compatibility behavior, so prefer explicit provider/model). If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default.
• models: the configured model catalog and allowlist for /model. Each entry can include alias (shortcut) and params (provider-specific, for example temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, chat_template_kwargs, extra_body/extraBody).
  • Safe edits: use openclaw config set agents.defaults.models '<json>' --strict-json --merge to add entries. config set refuses replacements that would remove existing allowlist entries unless you pass --replace.
  • Provider-scoped configure/onboarding flows merge selected provider models into this map and preserve unrelated providers already configured.
  • For direct OpenAI Responses models, server-side compaction is enabled automatically. Use params.responsesServerCompaction: false to stop injecting context_management, or params.responsesCompactThreshold to override the threshold. See OpenAI server-side compaction.
• params: global default provider parameters applied to all models. Set at agents.defaults.params (e.g. { cacheRetention: "long" }).
• params merge precedence (config): agents.defaults.params (global base) is overridden by agents.defaults.models["provider/model"].params (per-model), then agents.list[].params (matching agent id) overrides by key. See Prompt Caching for details.
• params.extra_body/params.extraBody: advanced pass-through JSON merged into api: "openai-completions" request bodies for OpenAI-compatible proxies. If it collides with generated request keys, the extra body wins; non-native completions routes still strip OpenAI-only store afterward.
• params.chat_template_kwargs: vLLM/OpenAI-compatible chat-template arguments merged into top-level api: "openai-completions" request bodies. For vllm/nemotron-3-* with thinking off, the bundled vLLM plugin automatically sends enable_thinking: false and force_nonempty_content: true; explicit chat_template_kwargs override generated defaults, and extra_body.chat_template_kwargs still has final precedence. For vLLM Qwen thinking controls, set params.qwenThinkingFormat to "chat-template" or "top-level" on that model entry.
• compat.supportedReasoningEfforts: per-model OpenAI-compatible reasoning effort list. Include "xhigh" for custom endpoints that truly accept it; OpenClaw then exposes /think xhigh in command menus, Gateway session rows, session patch validation, agent CLI validation, and llm-task validation for that configured provider/model. Use compat.reasoningEffortMap when the backend wants a provider-specific value for a canonical level.
• params.preserveThinking: Z.AI-only opt-in for preserved thinking. When enabled and thinking is on, OpenClaw sends thinking.clear_thinking: false and replays prior reasoning_content; see Z.AI thinking and preserved thinking.
• agentRuntime: default low-level agent runtime policy. Omitted id defaults to OpenClaw Pi. Use id: "pi" to force the built-in PI harness, id: "auto" to let registered plugin harnesses claim supported models and use PI when none match, a registered harness id such as id: "codex" to require that harness, or a supported CLI backend alias such as id: "claude-cli". Explicit plugin runtimes fail closed when the harness is unavailable or fails. Keep model refs canonical as provider/model; select Codex, Claude CLI, Gemini CLI, and other execution backends through runtime config instead of legacy runtime provider prefixes. See Agent runtimes for how this differs from provider/model selection.
• Config writers that mutate these fields (for example /models set, /models set-image, and fallback add/remove commands) save canonical object form and preserve existing fallback lists when possible.
• maxConcurrent: max parallel agent runs across sessions (each session still serialized). Default: 4.

​

agents.defaults.agentRuntime

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

• id: "auto", "pi", a registered plugin harness id, or a supported CLI backend alias. The bundled Codex plugin registers codex; the bundled Anthropic plugin provides the claude-cli CLI backend.
• id: "auto" lets registered plugin harnesses claim supported turns and uses PI when no harness matches. An explicit plugin runtime such as id: "codex" requires that harness and fails closed if it is unavailable or fails.
• Environment override: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> overrides id for that process.
• For Codex-only deployments, set model: "openai/gpt-5.5" and agentRuntime.id: "codex".
• For Claude CLI deployments, prefer model: "anthropic/claude-opus-4-7" plus agentRuntime.id: "claude-cli". Legacy claude-cli/claude-opus-4-7 model refs still work for compatibility, but new config should keep provider/model selection canonical and put the execution backend in agentRuntime.id.
• Older runtime-policy keys are rewritten to agentRuntime by openclaw doctor --fix.
• Harness choice is pinned per session id after the first embedded run. Config/env changes affect new or reset sessions, not an existing transcript. Legacy sessions with transcript history but no recorded pin are treated as PI-pinned. /status reports the effective runtime, for example Runtime: OpenClaw Pi Default or Runtime: OpenAI Codex.
• This only controls text agent-turn execution. Media generation, vision, PDF, music, video, and TTS still use their provider/model settings.

​

agents.defaults.cliBackends

{
  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",
          // 或者在 CLI 接受提示词文件标志时使用 systemPromptFileArg。
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• CLI 后端以文本优先；工具始终被禁用。
• 当设置了 sessionArg 时支持会话。
• 当 imageArg 接受文件路径时支持图像透传。

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "你是一个乐于助人的助手。",
    },
  },
}

​

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 subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "如果存在则读取 HEARTBEAT.md...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every：持续时间字符串（ms/s/m/h）。默认值：30m（API key 认证）或 1h（OAuth 认证）。设为 0m 可禁用。
• includeSystemPromptSection：为 false 时，会从系统提示词中省略 Heartbeat 部分，并跳过将 HEARTBEAT.md 注入到引导上下文。默认值：true。
• suppressToolErrorWarnings：为 true 时，在心跳运行期间抑制工具错误警告载荷。
• timeoutSeconds：心跳代理轮次在被中止前允许的最长秒数。留空则使用 agents.defaults.timeoutSeconds。
• directPolicy：直接/DM 传递策略。allow（默认）允许直接目标传递。block 会抑制直接目标传递并发出 reason=dm-blocked。
• lightContext：为 true 时，心跳运行使用轻量级引导上下文，并且仅保留 HEARTBEAT.md 作为工作区引导文件。
• isolatedSession：为 true 时，每次心跳都在一个没有先前对话历史的新会话中运行。与 cron 的 sessionTarget: "isolated" 相同的隔离模式。可将每次心跳的 token 成本从约 100K 降到约 2-5K。
• skipWhenBusy：为 true 时，心跳会在额外繁忙通道上延后：子代理或嵌套命令工作。Cron 通道始终会延后心跳，即使没有此标志。
• 逐代理：设置 agents.list[].heartbeat。当任一代理定义了 heartbeat 时，只有这些代理会运行心跳。
• 心跳会运行完整的代理轮次——间隔越短，消耗的 token 越多。

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // 已注册压缩提供方插件的 id（可选）
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "精确保留部署 ID、工单 ID 和 host:port 对。", // 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", // 可选的仅压缩模型覆盖
        truncateAfterCompaction: true, // 压缩后轮转到更小的后继 JSONL
        maxActiveTranscriptBytes: "20mb", // 可选的本地预检压缩触发条件
        notifyUser: true, // 当压缩开始和完成时发送简短通知（默认：false）
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // 可选的仅 memory-flush 模型覆盖
          softThresholdTokens: 6000,
          systemPrompt: "会话即将压缩。请现在存储持久化记忆。",
          prompt: "将任何长期笔记写入 memory/YYYY-MM-DD.md；如果没有要存储的内容，请准确回复静默标记 NO_REPLY。",
        },
      },
    },
  },
}

• mode：default 或 safeguard（用于长历史的分块摘要）。参见 压缩。
• provider：已注册压缩提供方插件的 id。设置后，会调用该提供方的 summarize()，而不是内置的 LLM 摘要。失败时回退到内置实现。设置提供方会强制 mode: "safeguard"。参见 压缩。
• timeoutSeconds：OpenClaw 在中止单次压缩操作前允许的最长秒数。默认值：900。
• keepRecentTokens：Pi 截断点预算，用于逐字保留最近的转录尾部。手动 /compact 在显式设置时会遵守此值；否则手动压缩是一个硬检查点。
• identifierPolicy：strict（默认）、off 或 custom。strict 会在压缩摘要期间附加内置的模糊标识符保留指导。
• identifierInstructions：当 identifierPolicy=custom 时使用的可选自定义标识符保留文本。
• qualityGuard：对 safeguard 摘要的格式错误重试检查。默认在 safeguard 模式中启用；设置 enabled: false 可跳过审计。
• midTurnPrecheck：可选的 Pi 工具循环压力检查。启用时，OpenClaw 会在工具结果追加之后、下一次模型调用之前检查上下文压力。如果上下文已无法容纳，它会在提交提示词前中止当前尝试，并重用现有的预检查恢复路径来截断工具结果或压缩后重试。适用于 default 和 safeguard 两种压缩模式。默认：禁用。
• postCompactionSections：压缩后可重新注入的可选 AGENTS.md H2/H3 章节名。默认值为 ["Session Startup", "Red Lines"]；设为 [] 可禁用重新注入。未设置或显式设为该默认对时，也会接受较旧的 Every Session/Safety 标题作为兼容回退。
• model：仅用于压缩摘要的可选 provider/model-id 覆盖。当主会话需要使用一个模型，而压缩摘要应使用另一个模型时使用此项；未设置时，压缩会使用会话的主模型。
• maxActiveTranscriptBytes：可选的字节阈值（数字或如 "20mb" 这样的字符串），当活动 JSONL 增长超过阈值时，会在运行前触发正常的本地压缩。要求设置 truncateAfterCompaction，以便成功压缩后可以轮转到更小的后继转录。未设置或设为 0 时禁用。
• notifyUser：为 true 时，在压缩开始和完成时向用户发送简短通知（例如“正在压缩上下文…”和“压缩完成”）。默认禁用，以保持压缩过程静默。
• memoryFlush：自动压缩前的静默代理轮次，用于存储持久化记忆。当此整理轮次应保持在本地模型上时，将 model 设置为精确的 provider/model，例如 ollama/qwen3:8b；此覆盖不会继承活动会话的回退链。工作区只读时会跳过。

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // 持续时间（ms/s/m/h），默认单位：分钟
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[已清除旧工具结果内容]" },
        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",
          // 也支持 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,
          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,
        },
      },
    },
  },
}

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

​

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 }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        agentRuntime: { id: "auto" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { voiceId: "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 },
        },
      },
    ],
  },
}

• 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，则该代理会继承它；显式列表会替换默认值而不是合并，[] 表示无技能。
• 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）。在未设置逐消息或会话快速模式覆盖时生效。
• agentRuntime：可选的逐代理底层运行时策略覆盖。使用 { id: "codex" } 可让某个代理仅使用 Codex，而其他代理在 auto 模式下继续保留默认 PI 回退。
• runtime：可选的逐代理运行时描述符。当代理应默认使用 ACP harness 会话时，使用 type: "acp" 并设置 runtime.acp 默认值（agent、backend、mode、cwd）。
• 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）。

​

多代理路由

{
  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（缺省时默认为 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 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // 持续时间或 false
      maxDiskBytes: "500mb", // 可选的硬性预算
      highWaterBytes: "400mb", // 可选的清理目标
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // 默认空闲自动取消聚焦（小时）（`0` 禁用）
      maxAgeHours: 0, // 默认硬性最大时长（小时）（`0` 禁用）
    },
    mainKey: "main", // 旧字段（运行时始终使用 "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
    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,
      },
    },
  },
}

​

回复前缀

​

确认反应

• 默认使用活动代理的 identity.emoji，否则为 "👀"。设为 "" 可禁用。
• 按频道覆盖：channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。
• 解析顺序：账户 → 频道 → messages.ackReaction → identity 回退。
• 范围：group-mentions（默认）、group-all、direct、all。
• removeAckAfterReply：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支持反应的渠道上，在回复后移除确认反应。
• messages.statusReactions.enabled：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 在 Slack 和 Discord 上，如果未设置，则在确认反应处于活动状态时保持状态反应启用。 在 Telegram 上，需要显式设置为 true 才能启用生命周期状态反应。

​

入站防抖

​

TTS（文本转语音）

{
  messages: {
    tts: {
      auto: "always", // 关闭 | 始终 | 入站 | 被标记
      mode: "final", // 最终 | 全部
      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。
• 捆绑的语音提供方由插件拥有。如果设置了 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: {
        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: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• 当配置了多个 Talk 提供方时，talk.provider 必须与 talk.providers 中的某个键匹配。
• 旧版扁平化的 Talk 键（talk.voiceId、talk.voiceAliases、talk.modelId、talk.outputFormat、talk.apiKey）仅用于兼容，并会自动迁移到 talk.providers.<provider> 中。
• 语音 ID 会回退到 ELEVENLABS_VOICE_ID 或 SAG_VOICE_ID。
• providers.*.apiKey 接受明文字符串或 SecretRef 对象。
• ELEVENLABS_API_KEY 回退仅在未配置 Talk API key 时生效。
• providers.*.voiceAliases 允许 Talk 指令使用友好名称。
• providers.mlx.modelId 选择 macOS 本地 MLX 辅助程序使用的 Hugging Face 仓库。如果省略，macOS 将使用 mlx-community/Soprano-80M-bf16。
• macOS 的 MLX 播放会通过捆绑的 openclaw-mlx-tts 辅助程序运行（如果存在），否则通过 PATH 上的可执行文件运行；OPENCLAW_MLX_TTS_BIN 会覆盖开发环境中的辅助程序路径。
• speechLocale 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域标识符。留空则使用设备默认值。
• silenceTimeoutMs 控制 Talk 模式在用户沉默后等待多久再发送转录结果。未设置时将保留平台默认的暂停窗口（macOS 和 Android 为 700 ms，iOS 为 900 ms）。

​

相关

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