配置 — 智能体工作区和引导

agents.defaults.* 键用于文件系统范围、引导上下文注入、上下文预算映射、入站图像处理以及智能体时区。

`agents.defaults.workspace`¶

默认值：若设置了 OPENCLAW_WORKSPACE_DIR 则为其值，否则为 <state-dir>/workspace。默认安装下为 ~/.openclaw/workspace，命名配置文件下为 ~/.openclaw-<profile>/workspace。自定义 OPENCLAW_STATE_DIR 会将工作区保持在该状态目录下。

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

显式的 agents.defaults.workspace 值优先于 OPENCLAW_WORKSPACE_DIR。单个智能体直接使用此路径。在多智能体集群中，未设置自身 workspace 的智能体会使用 agent-id 子目录，这样就没有隐式所有者占用共享根目录。

`agents.defaults.cwd`¶

可选的工作目录，用于智能体回复运行。当引导文件（AGENTS.md、SOUL.md）和记忆保留在受管理的智能体工作区中时，可使用它在现有仓库中运行编码工具。

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    entries: { coder: { cwd: "~/path/to/app", sandbox: { mode: "off" } } },
  },
}

会话生成的工作目录优先，其次是 agents.entries.*.cwd，再其次是 agents.defaults.cwd。如果均未设置，工具将使用智能体工作区。路径会像 workspace 一样展开 ~；相对路径相对于 Gateway 进程工作目录解析。不同的工作目录需要非沙箱运行；沙箱运行会拒绝该设置。当目录不同时，系统提示会说明它们各自的角色，以便交付物保留在工作目录中。

`agents.defaults.repoRoot`¶

可选的仓库根目录，显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上查找以自动检测。

{
  agents: { defaults: { repoRoot: "~/path/to/openclaw" } },
}

`agents.defaults.skills`¶

可选的默认技能允许列表，适用于未设置 agents.entries.*.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.md、SOUL.md、IDENTITY.md、USER.md、BOOTSTRAP.md）的自动创建，但不禁用现有文件的注入。对于嵌入式运行时，除非按智能体覆盖，否则使用 contextInjection: "never" 来禁用注入。

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

`agents.defaults.skipOptionalBootstrapFiles`¶

跳过所选可选工作区文件的创建，同时仍写入必需的引导文件（AGENTS.md、BOOTSTRAP.md）。有效值：SOUL.md、USER.md 和 IDENTITY.md（HEARTBEAT.md 会被接受但不起作用，因为心跳上下文已移至 cron monitor scratch）。

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

`agents.defaults.contextInjection`¶

控制嵌入式运行时中的工作区引导文件注入。默认值："always"。这些模式不控制基于 CLI 的提示准备，也不阻止智能体使用工具读取文件。

"always"：使用正常的工作区引导注入，受运行的上下文模式和文件过滤器约束。
"continuation-skip"：在已记录完整引导轮次之后的合格延续轮次会跳过工作区引导的重新注入，从而减小提示大小。心跳运行、待处理的完整引导设置以及压缩后重试仍使用正常上下文解析。
"never"：在每一轮中禁用工作区引导和上下文文件注入，包括心跳和压缩恢复轮次。对于具有特殊免引导工作流的嵌入式智能体，请使用此模式。

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

按智能体覆盖：agents.entries.*.contextInjection。省略的值继承 agents.defaults.contextInjection。

`agents.defaults.bootstrapMaxChars`¶

每个工作区引导文件在截断前的最大字符数。默认值：20000。例外：USER.md 有固定的 4,000 字符上限；此设置只能降低 USER.md 的上限，不能提高。参见用户模型。

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

按智能体覆盖：agents.entries.*.bootstrapMaxChars。省略的值继承 agents.defaults.bootstrapMaxChars。

`agents.defaults.bootstrapTotalMaxChars`¶

所有工作区引导文件合计注入的最大总字符数。默认值：60000。

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

按智能体覆盖：agents.entries.*.bootstrapTotalMaxChars。省略的值继承 agents.defaults.bootstrapTotalMaxChars。

按智能体的引导配置文件覆盖¶

当某个智能体需要与共享默认值不同的提示注入行为时，可使用按智能体的引导配置文件覆盖。省略的字段继承自 agents.defaults。

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

引导截断通知¶

当引导上下文被截断时，OpenClaw 始终会在系统提示中注入一条简洁的、智能体可见的通知，说明某些引导文件已被截断，请直接阅读受影响的文件。此通知是内置的且不可配置，并且故意省略了每文件的诊断信息：文件名、原始计数与注入计数以及限制原因保留在上下文/状态报告和日志等诊断信息中。

上下文预算归属图¶

OpenClaw 拥有多个高容量提示/上下文预算，并且它们被有意按子系统拆分，而不是全部通过一个通用配置项来控制。

预算	覆盖范围
`agents.defaults.bootstrapMaxChars` / `bootstrapTotalMaxChars`	常规工作区引导注入
`agents.defaults.startupContext.*`	一次性重置/启动模型运行前奏，包括最近的每日 `memory/*.md` 文件。单独发送 `/new` 和 `/reset` 只会确认重置，不会调用模型
`skills.limits.*`	注入到系统提示中的紧凑技能列表
`agents.defaults.contextLimits.*`	受限的运行时摘录和注入的运行时自有块

对应的按智能体覆盖项：

agents.entries.*.skillsLimits.maxSkillsPromptChars
agents.entries.*.contextInjection
agents.entries.*.bootstrapMaxChars
agents.entries.*.bootstrapTotalMaxChars
agents.entries.*.contextLimits.*

`agents.defaults.startupContext`¶

控制重置/启动模型运行时注入的首轮启动前奏。单独发送 /new 和 /reset 命令会确认重置，但不会调用模型，因此不会加载此前奏。

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

`agents.defaults.contextLimits`¶

用于受限运行时上下文区域的共享默认值。

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        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`¶

用于共享 contextLimits 设置的按智能体覆盖项。未指定的字段继承自 agents.defaults.contextLimits。

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

`skills.limits.maxSkillsPromptChars`¶

注入系统提示的紧凑技能列表的全局上限。这不影响按需读取 SKILL.md 文件。

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

`agents.entries.*.skillsLimits.maxSkillsPromptChars`¶

技能提示预算的按智能体覆盖项。

{
  agents: {
    entries: {
      "tiny-local": { skillsLimits: { maxSkillsPromptChars: 6000 } },
    },
  },
}

`agents.defaults.imageMaxDimensionPx`¶

在调用提供商之前，对话记录/工具图像块中图像最长边的最大像素尺寸。默认值：1200。

较低的值通常会减少视觉 token 的使用量，并降低截图密集型运行中的请求负载大小。较高的值会保留更多视觉细节。

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

`agents.defaults.imageQuality`¶

图像工具对从文件路径、URL 和媒体引用加载的图像采用的压缩/细节偏好。默认值：auto。

OpenClaw 会根据所选的图像模型调整缩放阶梯。例如，Claude Opus 4.8、OpenAI GPT-6 Astra、Qwen VL 和托管的 Llama 4 视觉模型可以使用比旧版/默认高细节视觉路径更大的图像；而在 auto 模式下，多图像轮次会被更积极地压缩，以控制 token 和延迟成本。

值：

auto：根据模型限制和图像数量进行调整。
efficient：优先使用更小的图像，以降低 token 和字节使用量。
balanced：使用标准的中间档缩放阶梯。
high：为截图、图表和文档图像保留更多细节。

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

`agents.defaults.userTimezone`¶

消息信封、排队中的系统事件以及系统提示中的本地日期上下文所使用的时区。若未设置，则回退到主机时区。

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

配置 — 智能体工作区和引导

agents.defaults.workspace¶

agents.defaults.cwd¶

agents.defaults.repoRoot¶

agents.defaults.skills¶

agents.defaults.skipBootstrap¶

agents.defaults.skipOptionalBootstrapFiles¶

agents.defaults.contextInjection¶

agents.defaults.bootstrapMaxChars¶

agents.defaults.bootstrapTotalMaxChars¶