Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

智能体运行时是拥有一个已准备模型循环的组件：它 接收提示词，驱动模型输出，处理原生工具调用，并将 完成的轮次返回给 OpenClaw。 运行时很容易和提供商混淆，因为两者都会出现在模型 配置附近。它们是不同层：
层级示例含义
提供商openai, anthropic, openai-codexOpenClaw 如何认证、发现模型并命名模型引用。
模型gpt-5.5, claude-opus-4-6为智能体轮次选择的模型。
智能体运行时pi, codex, claude-cli执行已准备轮次的底层循环或后端。
渠道Telegram, Discord, Slack, WhatsApp消息进入和离开 OpenClaw 的位置。
你也会在代码中看到 harness 这个词。harness 是提供智能体运行时的实现。 例如，内置的 Codex harness 实现了 codex 运行时。公共配置在提供商或模型条目上使用 agentRuntime.id； 整智能体运行时键是旧版配置，会被忽略。 openclaw doctor --fix 会移除旧的整智能体运行时固定项，并在需要时将 旧版运行时模型引用重写为规范的提供商/模型引用，加上模型级运行时策略。 运行时分为两类：
  • 嵌入式 harness 在 OpenClaw 已准备的智能体循环内运行。当前包括 内置的 pi 运行时，以及已注册的插件 harness，例如 codex。
  • CLI 后端 会运行本地 CLI 进程，同时保持模型引用规范。例如， anthropic/claude-opus-4-7 加上模型级 agentRuntime.id: "claude-cli" 表示“选择 Anthropic 模型，通过 Claude CLI 执行”。claude-cli 不是嵌入式 harness id， 不得传给 AgentHarness 选择逻辑。

​
Codex 表面

大多数混淆来自多个不同表面共用 Codex 名称：
表面OpenClaw 名称/配置作用
原生 Codex app-server 运行时openai/* 模型引用通过 Codex app-server 运行 OpenAI 嵌入式智能体轮次。这是常见的 ChatGPT/Codex 订阅设置。
Codex OAuth 认证配置文件openai-codex 认证提供商存储 Codex app-server harness 使用的 ChatGPT/Codex 订阅认证。
Codex ACP 适配器runtime: "acp", agentId: "codex"通过外部 ACP/acpx 控制平面运行 Codex。仅在明确要求 ACP/acpx 时使用。
原生 Codex 聊天控制命令集/codex ...从聊天中绑定、恢复、Steer、停止和检查 Codex app-server 线程。
非智能体表面的 OpenAI Platform API 路由openai/* 加 API 密钥认证用于直接 OpenAI API，例如图像、嵌入、语音和实时。
这些表面有意保持相互独立。启用 codex 插件会让原生 app-server 功能可用； openclaw doctor --fix 负责旧版 openai-codex/* 路由修复和过期会话固定清理。 现在为智能体模型选择 openai/* 表示“通过 Codex 运行它”，除非正在使用 非智能体 OpenAI API 表面。 常见的 ChatGPT/Codex 订阅设置使用 Codex OAuth 做认证，但保持模型引用为 openai/* 并选择 codex 运行时： 
{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
    },
  },
}
这意味着 OpenClaw 选择一个 OpenAI 模型引用，然后请求 Codex app-server 运行时运行嵌入式智能体轮次。它不表示“使用 API 计费”，也不表示渠道、 模型提供商目录或 OpenClaw 会话存储会变成 Codex。 启用内置 codex 插件时，自然语言 Codex 控制应使用原生 /codex 命令表面 （/codex bind、/codex threads、/codex resume、/codex steer、/codex stop）， 而不是 ACP。仅当用户明确要求 ACP/acpx 或正在测试 ACP 适配器路径时， 才对 Codex 使用 ACP。Claude Code、Gemini CLI、OpenCode、Cursor 和类似外部 harness 仍使用 ACP。 这是面向智能体的决策树：
  1. 如果用户要求 Codex 绑定/控制/线程/恢复/Steer/停止，在启用内置 codex 插件时使用原生 /codex 命令表面。
  2. 如果用户要求 Codex 作为嵌入式运行时，或想要正常的订阅支持 Codex 智能体体验，使用 openai/<model>。
  3. 如果用户明确为 OpenAI 模型选择 PI，保持模型引用为 openai/<model>， 并将提供商/模型运行时策略设置为 agentRuntime.id: "pi"。选中的 openai-codex 认证配置文件会在内部通过 PI 的旧版 Codex 认证传输路由。
  4. 如果旧版配置仍包含 openai-codex/* 模型引用，用 openclaw doctor --fix 将其修复为 openai/<model>；doctor 会在旧模型引用隐含 Codex 认证路由的位置，通过添加提供商/模型级 agentRuntime.id: "codex" 来保留该意图。
  5. 如果用户明确说 ACP、acpx 或 Codex ACP 适配器，使用 runtime: "acp" 和 agentId: "codex" 的 ACP。
  6. 如果请求面向 Claude Code、Gemini CLI、OpenCode、Cursor、Droid 或其他外部 harness，使用 ACP/acpx，而不是原生子智能体运行时。
你的意思是…使用…
Codex app-server 聊天/线程控制内置 codex 插件的 /codex ...
Codex app-server 嵌入式智能体运行时openai/* 智能体模型引用
OpenAI Codex OAuthopenai-codex 认证配置文件
Claude Code 或其他外部 harnessACP/acpx
关于 OpenAI 系列前缀拆分，请参阅 OpenAI 和 模型提供商。关于 Codex 运行时支持契约，请参阅 Codex harness runtime。

​
运行时所有权

不同运行时拥有循环中不同范围的内容。
表面OpenClaw PI 嵌入式Codex app-server
模型循环所有者OpenClaw 通过 PI 嵌入式运行器Codex app-server
规范线程状态OpenClaw transcriptCodex 线程，加上 OpenClaw transcript 镜像
OpenClaw 动态工具原生 OpenClaw 工具循环通过 Codex 适配器桥接
原生 shell 和文件工具PI/OpenClaw 路径Codex 原生工具，在支持的位置通过原生钩子桥接
上下文引擎原生 OpenClaw 上下文组装OpenClaw 将项目上下文组装到 Codex 轮次中
压缩OpenClaw 或选定的上下文引擎Codex 原生压缩，带 OpenClaw 通知和镜像维护
渠道投递OpenClawOpenClaw
这种所有权拆分是主要设计规则：
  • 如果 OpenClaw 拥有该表面，OpenClaw 就可以提供正常的插件钩子行为。
  • 如果原生运行时拥有该表面，OpenClaw 需要运行时事件或原生钩子。
  • 如果原生运行时拥有规范线程状态，OpenClaw 应镜像并投射上下文，而不是重写不受支持的内部实现。

​
运行时选择

OpenClaw 在提供商和模型解析之后选择嵌入式运行时：
  1. 模型级运行时策略优先。它可以位于已配置的提供商模型条目中，也可以位于 agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime。
  2. 其次是提供商级运行时策略，位于 models.providers.<provider>.agentRuntime。
  3. 在 auto 模式下，已注册的插件运行时可以声明支持的提供商/模型组合。
  4. 如果在 auto 模式下没有运行时声明某个轮次，OpenClaw 会使用 PI 作为 兼容性运行时。如果运行必须严格，请使用显式运行时 id。
整会话和整智能体运行时固定项会被忽略。这包括 OPENCLAW_AGENT_RUNTIME、会话 agentHarnessId/agentRuntimeOverride 状态、 agents.defaults.agentRuntime 和 agents.list[].agentRuntime。运行 openclaw doctor --fix 可移除过期的整智能体运行时配置，并在 OpenClaw 能够保留意图时转换 旧版运行时模型引用。 显式提供商/模型插件运行时会失败关闭。例如，提供商或模型上的 agentRuntime.id: "codex" 表示 Codex，或明确的选择/运行时错误； 它绝不会被静默路由回 PI。 CLI 后端别名不同于嵌入式 harness id。首选的 Claude CLI 形式是： 
{
  agents: {
    defaults: {
      model: "anthropic/claude-opus-4-7",
      models: {
        "anthropic/claude-opus-4-7": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}
为兼容性仍支持 claude-cli/claude-opus-4-7 等旧版引用，但新配置应保持 提供商/模型规范，并将执行后端放入提供商/模型运行时策略中。 对大多数提供商而言，auto 模式有意保持保守。OpenAI 智能体模型是例外： 未设置运行时和 auto 都会解析到 Codex harness。显式 PI 运行时配置仍是 openai/* 智能体轮次的选择性兼容路径；当它与选中的 openai-codex 认证配置文件配对时， OpenClaw 会在内部通过旧版 Codex 认证传输路由 PI，同时保持公共模型引用为 openai/*。过期的 OpenAI PI 会话固定项会被运行时选择忽略，并可用 openclaw doctor --fix 清理。 如果 openclaw doctor 警告 codex 插件已启用，但配置中仍有 openai-codex/*，请将其视为旧版路由状态。运行 openclaw doctor --fix 将其重写为带 Codex 运行时的 openai/*。

​
兼容性契约

当运行时不是 PI 时，它应记录它支持哪些 OpenClaw 表面。 运行时文档请使用这种结构：
问题为什么重要
谁拥有模型循环？决定重试、工具继续执行和最终答案决策发生在哪里。
谁拥有规范线程历史？决定 OpenClaw 能否编辑历史，还是只能镜像历史。
OpenClaw 动态工具是否可用？消息、会话、cron 和 OpenClaw 拥有的工具都依赖它。
动态工具钩子是否可用？插件期望在 OpenClaw 拥有的工具周围使用 before_tool_call、after_tool_call 和中间件。
原生工具钩子是否可用？Shell、patch 和运行时拥有的工具需要原生钩子支持，以便执行策略和观察。
上下文引擎生命周期是否运行？记忆和上下文插件依赖组装、摄取、轮次后处理和压缩生命周期。
暴露了哪些压缩数据？某些插件只需要通知，而其他插件需要保留/丢弃的元数据。
哪些内容是有意不支持的？用户不应在原生运行时拥有更多状态的地方假定 PI 等价性。
Codex 运行时支持契约记录在 Codex harness runtime 中。

​
Status 标签

Status 输出可能同时显示 Execution 和 Runtime 标签。应将它们视为 诊断信息，而不是提供商名称。
  • 像 openai/gpt-5.5 这样的模型引用会告诉你选中的提供商/模型。
  • 像 codex 这样的运行时 id 会告诉你哪个循环正在执行该轮次。
  • 像 Telegram 或 Discord 这样的渠道标签会告诉你对话发生在哪里。
如果一次运行仍显示意外的运行时，请先检查所选提供商/模型的 运行时策略。旧版会话运行时固定不再决定路由。

​
相关内容