在 OpenClaw 中，Agent 运行时是执行模型循环的底层组件。本页帮你区分四种运行时：PI（内嵌宿主）、Codex（ChatGPT 订阅后端）、ACP（外部框架）和 CLI 后端（如 Claude CLI），并说明如何通过 provider/model 级别的 agentRuntime.id 选择。全会话或全智能体的运行时引脚已被废弃，用 openclaw doctor --fix 清理旧配置。若用 Codex 订阅跑 OpenAI 模型，只需选 openai/* 模型引用，Codex 插件自动接管；如需强制 PI 运行，需显式设置 agentRuntime.id: 'pi'。

OpenClaw Agent 运行时配置：PI、Codex、ACP、CLI 后端选择

Agent 运行时是负责模型循环的组件：它接收提示词、驱动模型输出、处理原生工具调用，并将完成的回合返回给 OpenClaw。

运行时容易与 Provider 混淆，因为两者都在模型配置附近出现。它们是不同的层面：

层面	示例	含义
Provider	openai, anthropic, openai-codex	OpenClaw 如何认证、发现模型和命名模型引用。
Model	gpt-5.5, claude-opus-4-6	为智能体回合选择的模型。
Agent 运行时	pi, codex, claude-cli	执行已准备好回合的低层循环或后端。
Channel	Telegram, Discord, Slack, WhatsApp	消息进入和离开 OpenClaw 的渠道。

代码中还会看到 harness 一词。Harness 是提供 Agent 运行时的实现。例如，自带的 Codex harness 实现了 codex 运行时。公开配置使用 provider 或 model 条目上的 agentRuntime.id；全智能体运行时键已废弃并被忽略。运行 openclaw doctor --fix 会移除旧的全智能体运行时引脚，并将旧的运行时模型引用改写为规范的 provider/model 引用，必要时加上模型级运行时策略。

有两种运行时家族：

• 内嵌宿主：在 OpenClaw 准备好的智能体循环内运行。目前包括自带的 pi 运行时和已注册的插件宿主（如 codex）。
• CLI 后端：在本地运行 CLI 进程，同时保持模型引用规范。例如，anthropic/claude-opus-4-7 配合模型级 agentRuntime.id: "claude-cli" 表示“选择 Anthropic 模型，通过 Claude CLI 执行”。claude-cli 不是内嵌宿主 id，不能传给 AgentHarness 选择。

Codex 的不同面（避免混淆）

多个不同表面共用 Codex 名字是常见困惑源：

表面	OpenClaw 名称/配置	作用
原生 Codex 应用服务器运行时	openai/* 模型引用	通过 Codex 应用服务器运行 OpenAI 内嵌智能体回合。这是通常的 ChatGPT/Codex 订阅设置。
Codex OAuth 认证配置	openai-codex 认证 Provider	存储 ChatGPT/Codex 订阅认证，供 Codex 应用服务器宿主使用。
Codex ACP 适配器	runtime: "acp", agentId: "codex"	通过外部 ACP/acpx 控制平面运行 Codex。仅在明确要求 ACP/acpx 时使用。
原生 Codex 聊天控制命令集	/codex ...	从聊天中绑定、恢复、操控、停止和检查 Codex 应用服务器线程。
OpenAI Platform API 路由（非智能体表面）	openai/* + API 密钥认证	用于直接 OpenAI API，例如图像、嵌入、语音和实时 API。

这些表面是故意独立的。启用 codex 插件会使原生应用服务器功能可用；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 应用服务器运行时执行内嵌智能体回合。这不表示“使用 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 等外部宿主仍使用 ACP。

智能体决策树如下：

1. 如果用户要求 Codex 绑定/控制/线程/恢复/操控/停止，且 codex 插件已启用，使用原生 /codex 命令表面。
2. 如果用户要求 Codex 作为内嵌运行时 或想要订阅支持的 Codex 智能体体验，使用 openai/<model>。
3. 如果用户明确选择 PI 用于 OpenAI 模型，保持模型引用为 openai/<model>，并设置 provider/model 运行时策略为 agentRuntime.id: "pi"。已选择的 openai-codex 认证配置会通过 PI 的旧 Codex 认证传输路由。
4. 如果旧配置仍包含 openai-codex/* 模型引用，用 openclaw doctor --fix 修复为 openai/<model>；doctor 会在旧模型引用暗示 Codex 的地方添加 provider/model 级 agentRuntime.id: "codex"，以保持 Codex 认证路由。旧 codex-cli/* 模型引用 也会修复到相同的 openai/<model> Codex 应用服务器路由；OpenClaw 不再保留 Codex CLI 后端。
5. 如果用户明确说 ACP、acpx 或 Codex ACP 适配器，使用 ACP，runtime: "acp" 和 agentId: "codex"。
6. 如果请求是针对 Claude Code、Gemini CLI、OpenCode、Cursor、Droid 或其他外部宿主，使用 ACP/acpx，而不是原生子智能体运行时。

你指的是...	使用...
Codex 应用服务器聊天/线程控制	启用 codex 插件后的 /codex ...
Codex 应用服务器内嵌智能体运行时	openai/* 智能体模型引用
OpenAI Codex OAuth	openai-codex 认证配置
Claude Code 或其他外部宿主	ACP/acpx

关于 OpenAI 系列前缀拆分，见 OpenAI 和 Model providers。Codex 运行时支持合约见 Codex harness runtime。

运行时所有权对比

不同运行时拥有循环的不同部分。

表面	OpenClaw PI 内嵌	Codex 应用服务器
模型循环所有者	OpenClaw 通过 PI 内嵌运行器	Codex 应用服务器
规范线程状态	OpenClaw 记录	Codex 线程，加上 OpenClaw 记录镜像
OpenClaw 动态工具	原生 OpenClaw 工具循环	通过 Codex 适配器桥接
原生 shell 和文件工具	PI/OpenClaw 路径	Codex 原生工具，在支持处通过原生钩子桥接
上下文引擎	原生 OpenClaw 上下文组装	OpenClaw 将组装好的上下文投影到 Codex 回合
压缩	OpenClaw 或选定的上下文引擎	Codex 原生压缩，OpenClaw 接收通知并维护镜像
渠道投递	OpenClaw	OpenClaw

所有权分离是主要设计规则：

• 如果 OpenClaw 拥有该表面，OpenClaw 能提供正常的插件钩子行为。
• 如果原生运行时拥有该表面，OpenClaw 需要运行时事件或原生钩子。
• 如果原生运行时拥有规范线程状态，OpenClaw 应镜像和投影上下文，而不是重写不支持的内部状态。

运行时选择规则与优先级

OpenClaw 在 Provider 和模型解析后选择内嵌运行时：

1. 模型级运行时策略优先。可存在于配置的 Provider 模型条目中，或 agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime。Provider 通配符如 agents.defaults.models["vllm/*"].agentRuntime 在精确模型策略之后应用，因此动态发现的 Provider 模型可共享同一运行时，而不覆盖精确的逐模型例外。
2. Provider 级运行时策略次之，位于 models.providers.<provider>.agentRuntime。
3. auto 模式下，已注册的插件运行时可以声明支持的 Provider/模型对。
4. 如果 auto 模式下没有运行时声明该回合，OpenClaw 使用 PI 作为兼容运行时。当运行必须严格时，使用显式运行时 id。

全会话和全智能体的运行时引脚被忽略。包括 OPENCLAW_AGENT_RUNTIME、会话 agentHarnessId/agentRuntimeOverride 状态、agents.defaults.agentRuntime 和 agents.list[].agentRuntime。运行 openclaw doctor --fix 移除过期全智能体运行时配置，并在能保留意图的地方转换旧运行时模型引用。

显式的 Provider/模型插件运行时采用失败关闭机制。例如，Provider 或模型上设置 agentRuntime.id: "codex" 意味着要么 Codex 运行，要么出现明确的选择/运行时错误；绝不会静默回退到 PI。

CLI 后端别名与内嵌宿主 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 仍为兼容性保留支持，但新配置应保持 provider/model 规范，并将执行后端放到 provider/model 运行时策略中。

旧 codex-cli/* 引用不同：doctor 会将其迁移到 openai/*，以通过 Codex 应用服务器宿主运行，而不是保留 Codex CLI 后端。

auto 模式对大多数 Provider 是保守的。OpenAI 智能体模型是例外：未设置运行时的 auto 都会解析为 Codex 宿主。显式 PI 运行时配置对于 openai/* 智能体回合是选择性加入的兼容性路由；当配合选定的 openai-codex 认证配置时，OpenClaw 在内部通过旧的 Codex 认证传输路由 PI，同时保持公共模型引用为 openai/*。过期的 OpenAI PI 会话引脚会被运行时选择忽略，可用 openclaw doctor --fix 清理。

如果 openclaw doctor 警告 codex 插件已启用而配置中仍有 openai-codex/*，视为旧路由状态。运行 openclaw doctor --fix 将其重写为 openai/* 并附带 Codex 运行时。

兼容性合约（非 PI 运行时）

当运行时不是 PI 时，应记录它支持哪些 OpenClaw 表面。用以下表格形式：

问题	为什么重要
谁拥有模型循环？	决定重试、工具延续和最终答案决策发生在哪。
谁拥有规范线程历史？	决定 OpenClaw 能否编辑历史，或只能镜像。
OpenClaw 动态工具是否工作？	消息、会话、cron 和 OpenClaw 拥有的工具依赖于此。
动态工具钩子是否工作？	插件期望围绕 OpenClaw 拥有工具的 before_tool_call、after_tool_call 和中间件。
原生工具钩子是否工作？	Shell、patch 和运行时拥有的工具需要原生钩子支持策略和观察。
上下文引擎生命周期是否运行？	记忆和上下文插件依赖 assemble、ingest、after-turn 和压缩生命周期。
暴露了哪些压缩数据？	一些插件只需通知，其他需要保留/丢弃的元数据。
哪些是有意不支持的？	用户不应假设原生运行时拥有更多状态时与 PI 等价。

Codex 运行时支持合约记录在 Codex harness runtime。

状态输出中的运行时标签解读

状态输出中可能同时显示 Execution 和 Runtime 标签。将其视为诊断信息，而非 Provider 名称。

• 模型引用如 openai/gpt-5.5 告诉你选择的 Provider/模型。
• 运行时 id 如 codex 告诉你哪个循环在执行该回合。
• 渠道标签如 Telegram 或 Discord 告诉你对话发生在哪里。

如果运行仍显示意外的运行时，首先检查选定的 Provider/模型运行时策略。过期的会话运行时引脚不再决定路由。

相关文档

• Codex harness
• Codex harness runtime
• OpenAI
• Agent harness plugins
• Agent loop
• Models
• Status

常见问题

怎么区分 Provider、Model 和 Agent 运行时？

Provider 定义如何认证和发现模型（如 openai、anthropic）；Model 是具体的模型名（如 gpt-5.5）；Agent 运行时是执行模型循环的后端（如 pi、codex、claude-cli）。配置时只需在模型引用上加 agentRuntime.id，不需要修改 Provider 或 Model 本身。

openclaw doctor --fix 能修复什么运行时问题？

它能移除旧的全智能体运行时引脚（如 agents.defaults.agentRuntime），将 openai-codex/* 和 codex-cli/* 模型引用修复为 openai/<model> 并自动添加模型级运行时策略，还会清理过期会话运行时状态。运行后建议重新检查状态输出。

Codex 插件命令和 ACP 什么时候用？

启用自带的 codex 插件后，使用 /codex bind、/codex threads、/codex resume、/codex steer、/codex stop 控制 Codex 应用服务器线程。仅当用户明确要求 ACP/acpx 或 Codex ACP 适配器时，才使用 runtime: "acp" 和 agentId: "codex"。Claude Code、Gemini CLI、OpenCode、Cursor 等外部宿主始终走 ACP 路径。