【原理】OpenClaw Agent 运行时回顾一文清

本文基于v2026.7.1版本进行描述

📌 概述：

OpenClaw 内置了一个嵌入式智能体运行时（Embedded Agent Runtime），它不是一个外部的“训练场”或“测试台”，而是直接集成在 OpenClaw 核心中的一整套智能体循环（Agent Loop），负责：

• 接收用户输入（提示词）；
• 驱动语言模型（LLM）生成响应；
• 调用工具（Tools）并处理工具结果；
• 完成一轮或多轮对话，最终返回结果。

与“委托给外部 harness 进程”的方案不同，OpenClaw 的运行时是自主拥有的——它自己管理提示词组装、工具连接、会话存储和渠道交付。

每个配置好的智能体（如果你运行多个，可参考多智能体路由）都拥有自己独立的：

• 工作区（Workspace）：存放所有上下文文件和工具运行目录；
• 引导文件（Bootstrap files）：用于设定人格、记忆、工具使用说明等；
• 会话存储（Session Storage）：记录历史对话。

💡Agent 运行时就像是智能体的“大脑”，而工作区则是它的“记忆库”和“工具箱”。

🗂️ 工作区（Workspace）

每个智能体都必须有一个工作区目录。它既是工具执行的当前工作目录（cwd），也是所有上下文文件的存放地。

• 配置项：agents.defaults.workspace 或针对特定智能体的 agents.entries.*.workspace。
• 建议：运行 openclaw setup 自动创建 ~/.openclaw/openclaw.json（如果不存在）并初始化工作区文件。
• 完整工作区布局和备份指南，请参见 [Agent 工作区] 文档。

如果启用了沙箱模式（agents.defaults.sandbox），非主会话会使用 sandbox.workspaceRoot 下的临时工作区，实现隔离。

📁 工作区就是智能体的“本地硬盘”，所有长期记忆和个性化配置都放在这里。

📄 引导文件（Bootstrap Files）

在工作区根目录下，OpenClaw 会读取一组用户可编辑的 Markdown 文件，这些文件的内容会在新会话的第一轮被注入到系统提示词中，从而决定智能体的行为、性格和记忆。

⚠️ 重要：空文件会被跳过；过大的文件会被裁剪并附加标记（提示你查看完整内容）。缺失的文件（除 MEMORY.md 外）会注入一行“文件缺失”提示，但 openclaw setup 会生成安全的默认模板。

🎯 BOOTSTRAP.md 的特殊机制

• 仅在全新工作区（没有其他引导文件）时创建。
• 在待处理期间，它会一直保留在项目上下文中，并在系统提示词中添加“初始仪式”的引导说明——不会直接复制到用户消息中。
• 完成仪式后，用户删除此文件，后续重启不会重新创建，避免重复初始化。

🛡️ 工作区状态存储

OpenClaw 会将工作区的设置状态和“证明”（attestation）存储在共享 SQLite 数据库 ~/.openclaw/state/openclaw.sqlite 中。如果工作区被清空或消失，启动时会拒绝静默重新生成 BOOTSTRAP.md，防止意外覆盖。

旧版本使用 JSON 和 .attested 辅助文件，现在已废弃。运行 openclaw doctor –fix 可导入旧状态并清理。

🔒 完全禁用引导文件创建

如果你希望使用预先填充好的工作区，不想让 OpenClaw 自动创建任何引导文件，可以设置：

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

🧰 内置工具（Built‑in Tools）与 Skills

核心工具

OpenClaw 自带一组始终可用的核心工具：

• read：读取文件
• exec：执行命令
• edit：编辑文件
• write：写入文件
• 以及相关系统工具

这些工具受**工具策略（Tool Policy）**控制。对于 OpenAI 模型，apply_patch 默认启用，并受 tools.exec.applyPatch 相关配置限制。

⚠️ 注意：TOOLS.md 并不控制工具是否存在，它只是用来指导智能体如何按照你的意愿使用这些工具。

🧩 Skills（技能）

Skills 是预定义的“能力包”，可以加载到智能体中，扩展其功能。OpenClaw 按照以下优先级从高到低加载 Skills：

Skills 根目录可以包含分组文件夹（如 <workspace>/skills/personal/foo/SKILL.md），但 Skill 名称仍然通过 frontmatter 中的 name 字段扁平公开（例如 foo）。

💡 你可以通过配置或环境变量控制 Skills 的行为。

💬 会话（Session）管理

每个智能体的会话历史存储在独立的 SQLite 数据库中：

~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite

为了兼容旧版本，转录 JSONL 文件仍然可以保存在 ~/.openclaw/agents/<agentId>/sessions/ 下，但仅供迁移、导入导出或归档使用。活跃的智能体历史记录已全部迁移到 SQLite 中，OpenClaw 不会再去读取其他工具的会话文件夹。

会话 ID 是稳定且由 OpenClaw 自动生成的，你无需操心。

🌊 流式传输（Streaming）与分块（Chunking）

Steer（引导）机制

在运行期间，如果收到新的入站提示词，默认会通过 Steer 将其加入到当前运行中。具体行为：

• Steer 会在当前助手轮次执行完所有工具调用后、下一次 LLM 调用之前传递新提示词。
• 它不会跳过当前助手消息中剩余的工具调用。

命令控制：

• /queue steer 是活跃运行的默认行为。
• /queue followup 和 /queue collect 会让消息等待后续轮次，而不是立即 Steer。
• /queue interrupt 会中止当前活跃运行。

分块流式传输

分块流式传输会在每个助手内容块完成后立即发送。相关配置：

• agents.defaults.blockStreamingDefault：默认关闭（"off"）。
• agents.defaults.blockStreamingBreak：调整分块边界（text_end 与 message_end，默认 text_end）。
• agents.defaults.blockStreamingChunk：控制软分块字符数（默认 800‑1200 个字符，优先在段落分隔处拆分，其次换行，最后句子）。
• agents.defaults.blockStreamingCoalesce：合并流式分块以减少单行刷屏（基于空闲状态合并）。

💬 非 Telegram 渠道需要显式设置 *.streaming.block.enabled: true 才能启用分块回复。QQ Bot 默认会流式传输分块回复，除非设置 channels.qqbot.streaming.mode 为 "off"。

详细的工具摘要会在工具启动时发出（无防抖），如果可用，Control UI 会通过智能体事件流式传输工具输出。

🔗 模型引用（Model Reference）与配置

在配置中引用模型时（如 agents.defaults.model 和 agents.defaults.models），OpenClaw 使用 provider/model 的格式。

解析规则

如果默认提供商不再提供已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个过时的默认值。

📋 最小配置

至少需要设置：

• agents.defaults.workspace（工作区路径）
• channels.whatsapp.allowFrom（强烈建议，用于安全限制）

🚀 Agent 运行时（Agent Runtimes）

Agent 运行时负责执行已准备好的模型循环：接收提示词，驱动模型输出，处理原生工具调用，并将完成的轮次返回给 OpenClaw。

运行时 ≠ 提供商 ≠ 模型 ≠ 渠道

它们分属不同的层级，不要混淆：

Harness 是提供 Agent 运行时的实现（代码术语）。例如，内置的 Codex harness 实现了 codex 运行时。

运行时的两类

🧩 聚焦 Codex：多个界面，一个名字

“Codex”在 OpenClaw 中可能指代多个不同界面，容易混淆。我们用一张表来理清：

⚠️ 这些界面相互独立，启用 codex 插件即提供原生 app-server 功能。

决策树：何时用哪个 Codex？

需要 Codex 绑定/控制/线程/恢复/引导/停止？
└─> 启用内置 codex 插件，使用原生 /codex 命令界面

将 Codex 用作嵌入式运行时，或用常规订阅式 Codex 智能体体验？
└─> 使用 openai/<model> 模型引用（自动路由到 Codex app-server 运行时）

明确要求 ACP、acpx 或 Codex ACP 适配器？
└─> 设置 runtime: "acp" 和 agentId: "codex"

Claude Code、Gemini CLI、OpenCode、Cursor、Droid 等外部执行框架？
└─> 使用 ACP/acpx，而不是原生子智能体运行时

🏛️ 运行时所有权（Runtime Ownership）

不同运行时负责循环中的不同部分，理解“谁拥有什么”至关重要。

设计原则：如果某个界面由 OpenClaw 所有，则能提供正常的插件钩子行为；若由原生运行时所有，则需要运行时事件或原生钩子。

⚙️ 运行时选择（Runtime Selection）

OpenClaw 在解析提供商和模型后，按下述顺序选择嵌入式运行时：

优先级说明

⚠️ 过时的配置：整个会话级或智能体级的运行时固定配置（如 OPENCLAW_AGENT_RUNTIME、agents.defaults.agentRuntime）已被忽略。运行 openclaw doctor –fix 可清理这些过期项。

CLI 后端别名与配置示例

推荐的 Claude CLI 配置：

{
agents: {
defaults: {
model: "anthropic/claude-opus-5",
models: {
"anthropic/claude-opus-5": {
agentRuntime: { id: "claude-cli" }
}
}
}
}
}

旧版 claude-cli/claude-opus-4-7 等仍受支持，但建议使用上述规范格式。

🧩 GitHub Copilot 运行时

外部插件 @openclaw/copilot 注册了一个 copilot 运行时，由 GitHub Copilot CLI 提供支持。它声明使用 github-copilot 提供商，并且不会被 auto 选中，需要显式启用：

{
agents: {
defaults: {
model: "github-copilot/gpt-5.5",
models: {
"github-copilot/gpt-5.5": {
agentRuntime: { id: "copilot" }
}
}
}
}
}

该 harness 在 extensions/copilot/doctor-contract-api.ts 中声明其提供商、运行时、CLI 会话密钥和认证配置前缀，openclaw doctor 会自动加载。

🤝 兼容性契约（Compatibility Contract）

当运行时不是 OpenClaw（如 Codex、Copilot、Claude CLI 等）时，其文档应说明它支持哪些 OpenClaw 功能。

🏷️ 状态标签（Status Labels）

在状态输出中，会看到 Execution 和 Runtime 标签。请将它们视为诊断信息，而非提供商名称：

• openai/gpt-5.6-sol → 提供商/模型，表示所选模型。
• codex → 运行时 ID，表示执行该轮次的循环。
• Telegram 或 Discord → 渠道标签，表示对话发生的位置。

如果某次运行显示了非预期的运行时，请检查所选提供商/模型的运行时策略，并注意过期的会话运行时固定设置已不再决定路由。

🎯 小结

• 工作区是智能体的本地“家”，存放所有引导文件和工具环境。
• 引导文件定义了智能体的性格、记忆和使用规则。
• 内置工具与 Skills 提供了基础能力和扩展方式。
• 会话管理采用 SQLite 存储，稳定可靠。
• 流式传输支持精细控制，提升交互体验。
• 模型引用使用 provider/model 规范，解析灵活。
• Agent 运行时与提供商、模型、渠道分层解耦，选择策略明确。
• 兼容性契约帮助用户理解不同运行时的能力边界。
• 状态标签用于诊断，不混淆概念。

💖 希望能帮你更好地驾驭 OpenClaw，构建出强大又贴心的智能体！如有疑问，欢迎博文下留言，或查阅官方文档。