本文解决如何配置 OpenClaw Agent 工作区与运行时参数，包括工作区目录、Bootstrap 文件（AGENTS.md、SOUL.md、TOOLS.md 等）自动注入规则、Skills 加载优先级、会话存储路径和流式 steering 的行为。关键操作：使用 openclaw setup 创建工作区；设置 agents.defaults.workspace；通过 skipBootstrap: true 禁用 Bootstrap 文件创建。模型引用使用 provider/model 格式（例如 openrouter/moonshotai/kimi-k2）。适用于需要自定义 Agent 行为、排查注入文件未生效或调整流式传输的开发者。

OpenClaw Agent 运行时配置：工作区、Bootstrap 文件注入与会话机制

OpenClaw 在 Gateway 内运行单个嵌入式 Agent 运行时——每个 Gateway 对应一个 Agent 进程，该进程拥有自己的工作区、Bootstrap 文件和会话存储。本文覆盖运行时合约：工作区必须包含什么、哪些文件会被注入、会话如何启动。

工作区（必填）

OpenClaw 使用单一的 Agent 工作区目录（agents.defaults.workspace）作为 Agent 的唯一工作目录（cwd），工具调用和上下文均基于此目录。

推荐做法：使用 openclaw setup 创建 ~/.openclaw/openclaw.json（如果缺失）并初始化工作区文件。

完整工作区布局与备份指南：Agent 工作区

如果启用了 agents.defaults.sandbox，非主会话可以在 agents.defaults.sandbox.workspaceRoot 下使用各自的沙盒工作区（参见 Gateway 配置）。

Bootstrap 文件（自动注入）

在 agents.defaults.workspace 目录下，OpenClaw 会读取以下用户可编辑的文件：

• AGENTS.md — 操作指令 + "记忆"
• SOUL.md — 角色设定、边界、语气
• TOOLS.md — 用户维护的工具说明（如 imsg、sag、使用约定）
• BOOTSTRAP.md — 一次性首次运行仪式（完成后自动删除）
• IDENTITY.md — Agent 名称/风格/emoji
• USER.md — 用户档案 + 首选称呼

在新会话的第一轮对话时，OpenClaw 会将这些文件的内容注入 Project Context（系统提示上下文）。

空文件会被跳过。过大的文件会被截断并附加标记，保持 prompt 精简（如需完整内容请直接读取文件）。

如果某个文件缺失，OpenClaw 会注入一行"文件缺失"标记（openclaw setup 会创建安全的默认模板）。

BOOTSTRAP.md 只在全新工作区（不存在其他 Bootstrap 文件）时创建。在 Bootstrap 待处理期间，OpenClaw 会将其保留在 Project Context 中，并添加系统提示指导完成初始化仪式（而非复制到用户消息）。完成仪式后删除 BOOTSTRAP.md，后续重启不会重新创建。

如果想完全禁用 Bootstrap 文件创建（例如工作区已被预填充），设置：

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

内置工具

核心工具（read/exec/edit/write 及相关系统工具）始终可用，受工具策略约束。apply_patch 是可选工具，由 tools.exec.applyPatch 控制开关。TOOLS.md 不控制工具是否存在，它只是指导 Agent 如何使用这些工具的说明。

Skills

OpenClaw 从以下位置加载 Skills（按优先级从高到低）：

• 工作区：<workspace>/skills
• 项目 Agent skills：<workspace>/.agents/skills
• 个人 Agent skills：~/.agents/skills
• 托管/本地：~/.openclaw/skills
• 内置（随安装包捆绑）
• 额外技能目录：skills.load.extraDirs

Skills 可通过配置或环境变量控制开关（参见 Gateway 配置 中的 skills 配置项）。

运行时边界

嵌入式 Agent 运行时基于 Pi Agent 核心构建（模型、工具、prompt 管道）。会话管理、服务发现、工具连接和渠道投递是 OpenClaw 在此核心之上的封装层。

会话

会话记录以 JSONL 格式存储在：

• ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

会话 ID 由 OpenClaw 分配，保持稳定。其他工具的历史会话目录不会被读取。

流式传输时的方向调整（Steering）

默认情况下，运行时收到的入站 prompt 会被引导（steered）至当前运行中。Steering 会在当前 Assistant 轮次完成所有工具调用之后、下次 LLM 调用之前投递，不再跳过当前 Assistant 消息中剩余的工具调用。

/queue steer 是默认的活动运行行为。/queue followup 和 /queue collect 会将消息等待到后续轮次，而非 steering。/queue interrupt 会中止活动运行。详见 Queue 和 Steering queue。

Block streaming 会在每个 Assistant block 完成后立即发送；默认关闭（agents.defaults.blockStreamingDefault: "off"）。可通过 agents.defaults.blockStreamingBreak 调整边界（text_end 或 message_end，默认 text_end）。软分块控制：agents.defaults.blockStreamingChunk（默认 800–1200 字符，优先在段落换行处分割，其次是换行符，最后是句子边界）。通过 agents.defaults.blockStreamingCoalesce 合并流式 chunk，减少单行刷屏（基于空闲检测在发送前合并）。非 Telegram 渠道需要显式设置 *.blockStreaming: true 才能启用 block replies。工具摘要在工具启动时立即输出（无防抖）；Control UI 在可用时通过 Agent 事件流式传输工具输出。更多详情：流式传输与分块。

模型引用

配置中的模型引用（如 agents.defaults.model 和 agents.defaults.models）通过第一个 / 拆分 provider 和 model。

• 配置模型时使用 provider/model 格式。
• 如果模型 ID 本身包含 /（OpenRouter 风格），必须加上 provider 前缀（例如：openrouter/moonshotai/kimi-k2）。
• 省略 provider 时，OpenClaw 会依次尝试：别名 → 精确匹配已配置 provider 中该 model ID 的唯一 provider → 回退到默认 provider。如果默认 provider 不再暴露其配置的默认模型，OpenClaw 会回退到第一个配置的 provider/model，而不显示已移除的 provider 默认值。

最小配置

至少需要设置：

• agents.defaults.workspace
• channels.whatsapp.allowFrom（强烈推荐）

---

下一篇：群聊 🦞

常见问题

Bootstrap 文件没生效怎么办？

检查文件是否存在于 agents.defaults.workspace 目录下，且文件名大小写正确（如 AGENTS.md）。文件过大可能被截断（会附加标记）。如果工作区不是全新创建，BOOTSTRAP.md 不会被自动生成。若仍不生效，尝试删除 ~/.openclaw/agents/<agentId>/sessions/ 下的旧会话 JSONL 文件，让新会话重新注入。

模型 ref 带斜杠怎么配置？

使用 provider/model 格式，例如 openrouter/moonshotai/kimi-k2。如果模型 ID 本身包含斜杠，必须显式指定 provider 前缀（openrouter/），否则 OpenClaw 无法正确解析。省略 provider 时只能用于不含斜杠的模型 ID。

如何禁用 Bootstrap 文件创建？

在配置中设置 agents.defaults.skipBootstrap: true。适用于预填充的工作区（例如通过 Git 或手动创建了 AGENTS.md 等文件）。设置后 OpenClaw 将不会创建 BOOTSTRAP.md，也不会在启动时等待初始化仪式。