配置 — 代理

​

代理默认值

​

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: 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.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[].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 tokens 时为 16000 字符，100K+ tokens 时为 32000 字符，200K+ tokens 时为 64000 字符。有效上限仍限制在模型上下文窗口的大约 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"],
      },
      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" }, // 全局默认提供方参数
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      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".
• toolProgressDetail: detail mode for /verbose tool summaries and progress-draft tool lines. Values: "explain" (default, compact human labels) or "raw" (append raw command/detail when available). Per-agent agents.list[].toolProgressDetail overrides this default.
• 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 OpenAI API-key or Codex OAuth access). 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, OpenRouter provider routing, chat_template_kwargs, extra_body/extraBody).
  • Use provider/* entries such as "openai/*": {} or "vllm/*": {} to show all discovered models for selected providers without manually listing every model id.
  • Add agentRuntime to a provider/* entry when every dynamically discovered model for that provider should use the same runtime. Exact provider/model runtime policy still wins over the wildcard.
  • 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.
• models.providers.openrouter.params.provider: OpenRouter-wide default provider-routing policy. OpenClaw forwards this to OpenRouter’s request provider object; per-model agents.defaults.models["openrouter/<model>"].params.provider and agent params override by key. See OpenRouter provider routing.
• 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. Configured vLLM Qwen and Nemotron thinking models expose binary /think choices (off, on) instead of the multi-level effort ladder.
• compat.thinkingFormat: OpenAI-compatible thinking payload style. Use "together" for Together-style reasoning.enabled, "qwen" for Qwen-style top-level enable_thinking, or "qwen-chat-template" for chat_template_kwargs.enable_thinking on Qwen-family backends that support request-level chat-template kwargs, such as vLLM. OpenClaw maps disabled thinking to false and enabled thinking to true, and configured vLLM Qwen models expose binary /think choices for these formats.
• 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.
• localService: optional provider-level process manager for local/self-hosted model servers. When the selected model belongs to that provider, OpenClaw probes healthUrl (or baseUrl + "/models"), starts command with args if the endpoint is down, waits up to readyTimeoutMs, then sends the model request. command must be an absolute path. idleStopMs: 0 keeps the process alive until OpenClaw exits; a positive value stops the OpenClaw-spawned process after that many idle milliseconds. See Local model services.
• Runtime policy belongs on providers or models, not on agents.defaults. Use models.providers.<provider>.agentRuntime for provider-wide rules or agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime for model-specific rules. OpenAI agent models on the official OpenAI provider select Codex by default.
• 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.

​

运行时策略

{
  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", 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 OpenClaw when no harness matches. An explicit plugin runtime such as id: "codex" requires that harness and fails closed if it is unavailable or fails.
• id: "pi" is accepted only as a deprecated alias for openclaw to preserve shipped configs from v2026.5.22 and earlier. New config should use openclaw.
• Runtime precedence is exact model policy first (agents.list[].models["provider/model"], agents.defaults.models["provider/model"], or models.providers.<provider>.models[]), then agents.list[] / agents.defaults.models["provider/*"], then provider-wide policy at models.providers.<provider>.agentRuntime.
• Whole-agent runtime keys are legacy. agents.defaults.agentRuntime, agents.list[].agentRuntime, session runtime pins, and OPENCLAW_AGENT_RUNTIME are ignored by runtime selection. Run openclaw doctor --fix to remove stale values.
• OpenAI agent models use the Codex harness by default; provider/model agentRuntime.id: "codex" remains valid when you want to make that explicit.
• For Claude CLI deployments, prefer model: "anthropic/claude-opus-4-8" plus model-scoped 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 provider/model runtime policy.
• 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: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "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 接受文件路径时支持图像透传。
• reseedFromRawTranscriptWhenUncompacted: true 允许后端在第一个压缩摘要存在之前，从受限的原始 OpenClaw 转录尾部恢复被失效化的安全会话。认证配置文件或凭据 epoch 的变化仍然不会进行 raw reseed。

​

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 禁用
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // 默认：true；false 会从系统提示词中省略 Heartbeat 章节
        lightContext: false, // 默认：false；true 仅保留工作区引导文件中的 HEARTBEAT.md
        isolatedSession: false, // 默认：false；true 在全新会话中运行每次心跳（无对话历史）
        skipWhenBusy: false, // 默认：false；true 也会等待该代理的子代理/嵌套通道
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow（默认）| block
        target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ...
        prompt: "如果存在则读取 HEARTBEAT.md...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: duration string (ms/s/m/h). Default: 30m (API-key auth) or 1h (OAuth auth). Set to 0m to disable.
• includeSystemPromptSection: when false, omits the Heartbeat section from the system prompt and skips HEARTBEAT.md injection into bootstrap context. Default: true.
• suppressToolErrorWarnings: when true, suppresses tool error warning payloads during heartbeat runs.
• timeoutSeconds: maximum time in seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to use agents.defaults.timeoutSeconds when set, otherwise the heartbeat cadence capped at 600 seconds.
• directPolicy: direct/DM delivery policy. allow (default) permits direct-target delivery. block suppresses direct-target delivery and emits reason=dm-blocked.
• lightContext: when true, heartbeat runs use lightweight bootstrap context and keep only HEARTBEAT.md from workspace bootstrap files.
• isolatedSession: when true, each heartbeat runs in a fresh session with no prior conversation history. Same isolation pattern as cron sessionTarget: "isolated". Reduces per-heartbeat token cost from ~100K to ~2-5K tokens.
• skipWhenBusy: when true, heartbeat runs defer on that agent’s extra busy lanes: its own session-keyed subagent or nested command work. Cron lanes always defer heartbeats, even without this flag.
• Per-agent: set agents.list[].heartbeat. When any agent defines heartbeat, only those agents run heartbeats.
• Heartbeats run full agent turns — shorter intervals burn more tokens.

​

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 tool-loop pressure check
        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, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // 可选的仅 memory-flush 模型覆盖
          softThresholdTokens: 6000,
          systemPrompt: "会话即将压缩。请现在存储持久化记忆。",
          prompt: "将任何长期笔记写入 memory/YYYY-MM-DD.md；如果没有要存储的内容，请准确回复静默标记 NO_REPLY。",
        },
      },
    },
  },
}

• mode: default or safeguard (chunked summarization for long histories). See Compaction.
• provider: id of a registered compaction provider plugin. When set, the provider’s summarize() is called instead of built-in LLM summarization. Falls back to built-in on failure. Setting a provider forces mode: "safeguard". See Compaction.
• timeoutSeconds: maximum seconds allowed for a single compaction operation before OpenClaw aborts it. Default: 900.
• keepRecentTokens: agent cut-point budget for keeping the most recent transcript tail verbatim. Manual /compact honors this when explicitly set; otherwise manual compaction is a hard checkpoint.
• identifierPolicy: strict (default), off, or custom. strict prepends built-in opaque identifier retention guidance during compaction summarization.
• identifierInstructions: optional custom identifier-preservation text used when identifierPolicy=custom.
• qualityGuard: retry-on-malformed-output checks for safeguard summaries. Enabled by default in safeguard mode; set enabled: false to skip the audit.
• midTurnPrecheck: optional tool-loop pressure check. When enabled: true, OpenClaw checks context pressure after tool results are appended and before the next model call. If the context no longer fits, it aborts the current attempt before submitting the prompt and reuses the existing precheck recovery path to truncate tool results or compact and retry. Works with both default and safeguard compaction modes. Default: disabled.
• postCompactionSections: optional AGENTS.md H2/H3 section names to re-inject after compaction. Reinjection is disabled when unset or set to []. Explicitly setting ["Session Startup", "Red Lines"] enables that pair and preserves the legacy Every Session/Safety fallback. Enable this only when the extra context is worth the risk of duplicating project guidance already captured in the compaction summary.
• model: optional provider/model-id override for compaction summarization only. Use this when the main session should keep one model but compaction summaries should run on another; when unset, compaction uses the session’s primary model.
• maxActiveTranscriptBytes: optional byte threshold (number or strings like "20mb") that triggers normal local compaction before a run when the active JSONL grows past the threshold. Requires truncateAfterCompaction so successful compaction can rotate to a smaller successor transcript. Disabled when unset or 0.
• notifyUser: when true, sends brief notices to the user when compaction starts and when it completes (for example, “Compacting context…” and “Compaction complete”). Disabled by default to keep compaction silent.
• memoryFlush: silent agentic turn before auto-compaction to store durable memories. Set model to an exact provider/model such as ollama/qwen3:8b when this housekeeping turn should stay on a local model; the override does not inherit the active session fallback chain. Skipped when workspace is read-only.

​

agents.defaults.runRetries

{
  agents: {
    defaults: {
      runRetries: {
        base: 24,
        perProfile: 8,
        min: 32,
        max: 160,
      },
    },
    list: [
      {
        id: "main",
        runRetries: { max: 50 }, // 可选的逐代理覆盖
      },
    ],
  },
}

• base：外层运行循环的基础重试迭代次数。默认值：24。
• perProfile：每个回退配置候选额外获得的重试迭代次数。默认值：8。
• min：重试迭代次数的最小绝对限制。默认值：32。
• max：防止失控执行的重试迭代次数最大绝对限制。默认值：160。

​

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 (使用 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", // 可选
          gatewayEndpoint: "https://lab.example", // 可选
          policy: "strict", // 可选 OpenShell policy id
          providers: ["openai"], // 可选
          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", // 或 { primary, fallbacks }
        thinkingDefault: "high", // 逐代理思考级别覆盖
        reasoningDefault: "on", // 逐代理推理可见性覆盖
        fastModeDefault: false, // 逐代理快速模式覆盖
        params: { cacheRetention: "none" }, // 按键覆盖 agents.defaults.models 中的匹配默认值
        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 },
        },
      },
    ],
  },
}

• 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）。在没有逐消息或会话快速模式覆盖时生效。
• models：可选的逐代理模型目录/运行时覆盖，按完整的 provider/model id 键入。使用 models["provider/model"].agentRuntime 表示逐代理运行时例外。
• runtime：可选的逐代理运行时描述符。若代理默认应使用 ACP 框架会话，可使用带有 runtime.acp 默认值（agent、backend、mode、cwd）的 type: "acp"。
• identity.avatar：工作区相对路径、http(s) URL 或 data: URI。
• identity 派生默认值：ackReaction 来自 emoji，mentionPatterns 来自 name/emoji。
• subagents.allowAgents：用于显式 sessions_spawn.agentId 目标的已配置代理 id 允许列表（["*"] = 任意已配置目标；默认：仅同一代理）。如果允许自我目标 agentId 调用，请包含请求者 id。已删除其代理配置的过期条目会被 sessions_spawn 拒绝，并从 agents_list 中省略；运行 openclaw doctor --fix 可清理它们，或者如果希望该目标仍可在继承默认值的同时保持可生成，可添加一个最小的 agents.list[] 条目。
• 沙箱继承保护：如果请求者会话已经处于沙箱中，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", // 主 | 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 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "enforce", // enforce (default) | warn
      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", // 群组提及 | 群组全部 | 私聊 | 全部
    removeAckAfterReply: false,
    queue: {
      mode: "followup", // 跟进 | 后续 | 收集 | 中断
      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 → identity 回退。
• 范围：group-mentions（默认）、group-all、direct、all。
• removeAckAfterReply：会在支持 reaction 的频道（如 Slack、Discord、Telegram、WhatsApp 和 iMessage）中，在回复后移除确认反应。
• messages.statusReactions.enabled：在 Slack、Discord、Telegram 和 WhatsApp 上启用生命周期状态反应。 在 Slack 和 Discord 上，如果不设置，当确认反应启用时状态反应仍保持启用。 在 Telegram 和 WhatsApp 上，必须显式设为 true 才会启用生命周期状态反应。
• messages.statusReactions.emojis：覆盖生命周期 emoji 键： queued、thinking、compacting、tool、coding、web、deploy、build、 concierge、done、error、stallSoft 和 stallHard。 Telegram 只允许固定的 reaction 集合，因此不受支持的已配置 emoji 会回退到 该聊天中最接近的受支持状态变体。

​

入站防抖

​

TTS（文本转语音）

{
  messages: {
    tts: {
      auto: "always", // 关闭 | 始终 | 入站 | 被标记
      mode: "final", // 最终 | 全部
      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-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",
          speakerVoice: "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: {
        speakerVoiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2",
          speakerVoice: "cedar",
        },
      },
      instructions: "以温暖的语气说话，并保持回答简短。",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• talk.provider 在配置了多个 Talk 提供方时，必须与 talk.providers 中的某个键匹配。
• 旧版扁平化 Talk 键（talk.voiceId、talk.voiceAliases、talk.modelId、talk.outputFormat、talk.apiKey）仅用于兼容性。运行 openclaw doctor --fix 可将持久化配置重写为 talk.providers.<provider>。
• 语音 ID 会回退到 ELEVENLABS_VOICE_ID 或 SAG_VOICE_ID。
• providers.*.apiKey 接受明文字符串或 SecretRef 对象。
• 仅当未配置 Talk API 密钥时，才会应用 ELEVENLABS_API_KEY 回退。
• providers.*.voiceAliases 允许 Talk 指令使用友好名称。
• providers.mlx.modelId 选择 macOS 本地 MLX helper 使用的 Hugging Face 仓库。如果省略，macOS 将使用 mlx-community/Soprano-80M-bf16。
• macOS MLX 播放会通过随附的 openclaw-mlx-tts helper（如果存在）或 PATH 上的可执行文件运行；OPENCLAW_MLX_TTS_BIN 会在开发时覆盖 helper 路径。
• consultThinkingLevel 控制 Control UI Talk realtime openclaw_agent_consult 调用背后完整 OpenClaw agent 运行的思考级别。保持未设置可保留正常的会话/模型行为。
• consultFastMode 为 Control UI Talk realtime consult 设置一次性 fast-mode 覆盖，而不会更改会话的正常 fast-mode 设置。
• speechLocale 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 ID。保持未设置可使用设备默认值。
• silenceTimeoutMs 控制 Talk 模式在用户静默后等待多久再发送转录文本。未设置时保留平台默认的暂停窗口（macOS 和 Android 为 700 ms，iOS 为 900 ms）。
• realtime.instructions 会将面向提供方的系统指令追加到 OpenClaw 内置的 realtime 提示词中，因此可以在不丢失默认 openclaw_agent_consult 指南的情况下配置语音风格。
• realtime.consultRouting 控制当 realtime 提供方在没有 openclaw_agent_consult 的情况下生成最终用户转录时的 Gateway relay 回退：provider-direct 保留直接的提供方回复，而 force-agent-consult 会将最终请求路由通过 OpenClaw。

​

相关

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