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

海兰2026-08-23 11:38

本文基于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 文件，这些文件的内容会在新会话的第一轮被注入到系统提示词中，从而决定智能体的行为、性格和记忆。

文件名 用途
AGENTS.md 操作说明 + "长期记忆"（类似系统指令）
SOUL.md 人格、边界、语气（定义"你是谁"）
TOOLS.md 用户维护的工具使用说明和约定
IDENTITY.md 智能体名称、风格、表情符号偏好
USER.md 用户资料 + 首选称呼
HEARTBEAT.md 心跳（Heartbeat）专用说明（定时任务等）
BOOTSTRAP.md 一次性的首次运行仪式（完成后自动删除）
MEMORY.md 根级长期记忆文件（仅当文件存在时才会注入）

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

🎯 BOOTSTRAP.md 的特殊机制

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

🛡️ 工作区状态存储

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

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

🔒 完全禁用引导文件创建

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

json5 复制代码 
{
  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：

  1. 工作区 ：<workspace>/skills
  2. 项目智能体 Skills ：<workspace>/.agents/skills
  3. 个人智能体 Skills ：~/.agents/skills
  4. 托管/本地 ：~/.openclaw/skills
  5. 内置：随安装自带
  6. 额外 Skills 文件夹 ：通过 skills.load.extraDirs 添加

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 的格式。

解析规则

  1. 配置时使用 provider/model。
  2. 如果模型 ID 本身包含 /（如 OpenRouter 风格），则必须包含提供商前缀，例如 openrouter/moonshotai/kimi-k2。
  3. 如果省略提供商，OpenClaw 会：
    • 先尝试查找别名；
    • 然后查找与该模型 ID 完全匹配的唯一已配置提供商；
    • 最后回退到已配置的默认提供商。

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

📋 最小配置

至少需要设置：

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

🚀 Agent 运行时（Agent Runtimes）

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

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

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

层级 示例 含义
提供商 anthropic, github-copilot, openai 如何认证、发现模型、命名模型引用
模型 claude-opus-4-6, gpt-5.6-sol 为智能体轮次选择的具体模型
Agent 运行时 claude-cli, codex, copilot, openclaw 执行已准备轮次的底层循环或后端
渠道 Discord, Slack, Telegram, WhatsApp 消息进入和离开 OpenClaw 的位置

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

运行时的两类

  1. 嵌入式执行框架 ：运行在 OpenClaw 已准备好的智能体循环内，如内置 openclaw 运行时，以及插件注册的 codex、copilot 等。
  2. CLI 后端 ：运行本地 CLI 进程，同时保持模型引用规范。例如，anthropic/claude-opus-5 搭配 agentRuntime.id: "claude-cli"，表示"选择 Anthropic 模型，通过 Claude CLI 执行"。

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

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

界面 OpenClaw 名称/配置 功能
原生 Codex app-server 运行时 openai/* 模型引用 通过 Codex app-server 运行 OpenAI 嵌入式智能体轮次（常规 ChatGPT/Codex 订阅设置）
Codex OAuth 认证配置文件 openai OAuth 配置文件 存储供 Codex app-server 执行框架使用的 ChatGPT/Codex 订阅认证信息
Codex ACP 适配器 runtime: "acp", agentId: "codex" 通过外部 ACP/acpx 控制平面运行 Codex（仅当明确要求 ACP 时使用）
原生 Codex 聊天控制命令集 /codex ... 从聊天中绑定、恢复、引导、停止和检查 Codex app-server 线程
非智能体 OpenAI Platform API 路由 openai/* + API 密钥认证 直接调用 OpenAI API（图像、嵌入、语音、实时 API 等）

⚠️ 这些界面相互独立，启用 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 嵌入式 Codex app-server
模型循环所有者 OpenClaw（通过嵌入式运行器） Codex app-server
规范线程状态 OpenClaw 对话记录 Codex 线程 + OpenClaw 镜像
OpenClaw 动态工具 原生 OpenClaw 工具循环 通过 Codex 适配器桥接
原生 shell/文件工具 OpenClaw 路径 Codex 原生工具，支持时通过原生钩子桥接
上下文引擎 原生 OpenClaw 上下文组装 OpenClaw 将组装后的上下文投射到 Codex 轮次
压缩 OpenClaw 或选定上下文引擎 Codex 原生压缩，OpenClaw 负责通知和镜像维护
渠道交付 OpenClaw OpenClaw

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

⚙️ 运行时选择（Runtime Selection）

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

优先级 条件 行为
1 存在模型范围运行时策略 使用模型范围的 agentRuntime.id
2 存在提供商范围运行时策略 使用提供商范围的 agentRuntime.id
3 自动模式 auto 且插件声明支持 使用声明的运行时
4 自动模式 auto 但无插件声明 回退到 openclaw
5 显式指定运行时 ID 使用指定运行时
--- 指定运行时不可用 ❌ 抛出明确错误，绝不静默回退

优先级说明

  1. 模型范围的运行时策略 ：位于 agents.defaults.models["provider/model"].agentRuntime 或 agents.entries.*.models["provider/model"].agentRuntime。支持提供商通配符（如 agents.defaults.models["vllm/*"].agentRuntime），但精确模型策略优先。
  2. 提供商范围的运行时策略 ：models.providers.<provider>.agentRuntime。
  3. auto 模式 ：已注册的插件运行时可以声明支持的提供商/模型组合。若没有任何运行时接管，则回退到 openclaw。
  4. 显式指定：使用确定的运行时 ID，若不可用则报错，不静默降级。

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

CLI 后端别名与配置示例

推荐的 Claude CLI 配置：

json5 复制代码 
{
  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 选中，需要显式启用：

json5 复制代码 
{
  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 功能。

问题 重要性 说明
谁负责模型循环？ ⭐⭐⭐ 决定重试、工具续接和最终答案决策发生处
谁负责规范线程历史记录？ ⭐⭐⭐ 决定 OpenClaw 能否编辑历史，还是只能镜像
OpenClaw 动态工具是否可用？ ⭐⭐⭐ 消息、会话、定时任务和 OpenClaw 自有工具依赖此功能
动态工具钩子是否可用？ ⭐⭐ 插件需要 before_tool_call、after_tool_call 以及中间件
原生工具钩子是否可用？ ⭐⭐ Shell、补丁等需要原生钩子支持策略和观测
上下文引擎生命周期是否运行？ ⭐⭐ 记忆和上下文插件依赖组装、摄取、轮次后处理和压缩生命周期
会公开哪些压缩数据？ ⭐ 某些插件只需要通知，其他需要保留/丢弃的元数据
哪些功能明确不受支持？ ⭐⭐⭐ 用户不应假定与 OpenClaw 完全等效

🏷️ 状态标签（Status Labels）

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

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

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

🎯 小结

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

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

相关推荐
民乐团扒谱机1 小时前
【微实验】物理启发神经网络（PINN）：当AI学会遵守物理定律（附matlab代码））
人工智能·神经网络·matlab
极客互动API1 小时前
企业微信 iPad 协议消息接口开发：文本 / 图片 / 群发消息的统一封装
人工智能·ios·微信·机器人·企业微信·ipad
达子6662 小时前
AI训练师图解_6.1_6.2_五大行业应用_NLP
人工智能·自然语言处理
新知图书2 小时前
11.4 基于扣子编程的实现过程（AI 数据质检工作流）
人工智能·agent·ai agent·智能体
YHL2 小时前
🚀 端侧 AI DEEPSEEK-R1-WEBGPU 项目实战（二）：封装进度条组件，看懂 React 事件与组件树
人工智能
皮皮狗工坊2 小时前
贡院计划第一弹：DeepSeek Harness考生翻墙抄了答案，还企图隐藏罪证
人工智能
Dawson Zhu2 小时前
Agent自我纠错死循环：从原理剖析到工程化防御体系构建
人工智能·语言模型·架构·aigc
weixin_471383032 小时前
22 多 Agent 架构
agent
ZJU_统一阿萨姆2 小时前
【算子开发】卷积算子基础实现与优化
人工智能·语言模型
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点03微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新042026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？05历年考研数学一、数学二、数学三真题试卷及答案PDF06Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片09VSCode+CodeX扩展，无法启动10如何新建文件夹？ 电脑新建文件夹的4种方法