Agent 运行时

OpenClaw 内置单一的嵌入式 Agent 运行时。

工作区（必填）

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 会将这些文件的内容直接注入 Agent 上下文。

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

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

BOOTSTRAP.md 只在全新工作区（没有其他 bootstrap 文件）时创建。完成初始化仪式后删除它，后续重启不会重新生成。

如果想完全禁用 bootstrap 文件创建（例如预置了工作区内容），可以设置：

{ agent: { skipBootstrap: true } }

内置工具

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

Skills

OpenClaw 从以下三个位置加载 Skills（工作区优先，同名时工作区覆盖其他位置）：

• 内置（随安装包捆绑）
• 托管/本地：~/.openclaw/skills
• 工作区：<workspace>/skills

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

运行时边界

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

会话

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

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

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

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

当队列模式为 steer 时，收到的消息会注入当前运行中。排队的 steering 消息会在当前 Assistant 轮次完成所有工具调用之后、下次 LLM 调用之前投递。Steering 不再跳过当前 Assistant 消息中剩余的工具调用，而是在下一个模型边界注入排队的消息。

当队列模式为 followup 或 collect 时，收到的消息会等到当前轮次结束，然后以排队的 payload 启动新的 Agent 轮次。队列模式和防抖/上限行为详见 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 的模型（仅适用于模型 ID 中不含 / 的情况）。

最小配置

至少需要设置：

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

---

下一篇：群聊 🦞