OpenClaw Codex harness：会话、凭据与计费

OpenClaw Codex harness 是官方 @openclaw/codex 插件：它将 OpenClaw agent 回合交给 OpenAI 的 Codex app-server，使 Codex 负责模型循环、线程恢复、工具继续执行和压缩。 它不是编码委派产品，不是计费层，而且——最容易让多数配置误入歧途的一点——它不能让 Codex 针对第三方 API 端点运行。你实际需要其中哪一种能力，正是本页要帮助你作出的判断。

先说明日期，确保这里没有未标日期的内容。npm 软件包 openclaw 的版本为 2026.9.5，要求 Node >=24.16.0 <25 || >=26.1.0；@openclaw/codex 的版本也是 2026.9.5，于 2026 年 9 月 18 日发布。两者均于 2026 年 9 月 21 日从注册表读取。三个无关项目也使用了这些名称，但它们的任何版本号都与此无关：pjasicek/OpenClaw 自称是 1997 年平台游戏 Captain Claw 的重新实现；不带作用域的 npm 软件包 codex 是一个“静态网站和代码文档生成器”，最后一次发布于 2012 年；而 OpenAI 的 CLI 是 @openai/codex（同日版本为 0.155.1）。

五个 OpenClaw 表面使用了“Codex”这一名称

OpenClaw 的 agent-runtimes 文档称这些项目“有意彼此独立”。选错项目，是配置看似正确却不起作用的最常见原因。

第六个名称完全不属于 OpenClaw。openclaw-code-agent 是一个第三方插件，可在后台运行带有计划审批和工作树隔离的编码会话；其自有 README 说明它独立于 OpenClaw 捆绑的 acpx 运行时插件和捆绑的核心 codex 插件。如果你来到这里是想要委派，而不是更换运行时，那么这是另一款产品，也使用不同的配置键。

启用 harness，并证明它已启用

文档规定的路径是执行两个命令——先安装插件，再登录。

openclaw plugins install @openclaw/codex
openclaw models auth login --provider openai

然后进行最低限度的配置。如果你使用 plugins.allow 列表，也要将 "codex" 添加到其中。

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
      },
    },
  },
  agents: {
    defaults: {
      // The docs' own example ref. Legacy codex-cli/* refs are
      // repaired to the same openai/<model> route by doctor --fix.
      model: "openai/gpt-6-astra",
    },
  },
}

harness 文档明确说明了两点。插件配置变更会在混合重新加载模式下自动生效，但现有聊天需要先执行 /new 或 /reset，这样下一回合才会根据当前配置解析 harness。有效工具配置必须允许原生 shell 和文件系统能力：coding 和 full允许，而 messaging 和 minimal 会禁用原生界面。普通 OpenClaw 沙箱或受限工具策略在同一份文档中属于更窄的限制——除非选择实验性的沙箱 exec-server 路径，否则会禁用原生代码模式；当沙箱确实禁用原生界面时，允许的 shell 命令仍可通过 sandbox_exec 访问。

版本要求已于 2026 年 9 月 21 日根据app-server 传输参考核查：该插件管理稳定版 Codex app-server 0.154.0，而显式自定义可执行文件、远程 app-server 和 macOS 桌面二进制文件必须报告可解析的语义版本 0.149.0 或更高。npm 的最新 @openai/codex 在同日为 0.155.1，因此受管理的固定版本落后一个补丁版本——这也是任何未注明日期、声称使用“Codex latest”的教程会在几天内过时的原因。迁移旧配置同样重要：agent-runtimes 页面称 OpenClaw 捆绑的 Codex CLI 后端已在 v2026.5.14 中移除，旧的 codex-cli/* 引用会通过 openclaw doctor --fix 修复为同一条 openai/<model> Codex app-server 路由；该命令负责旧版 Codex 路由的一般修复工作。

要验证这一点：基于 Codex 的回合会在 /status 下报告 Runtime: OpenAI Codex，而 /codex status、/codex models 和 /codex binding 会检查 app-server 状态。lint 命令——openclaw doctor --lint --only codex/managed-app-server --json——会检查受管理的二进制文件，但文档将其描述为只读检查，并将所选 Codex Desktop 二进制文件、显式自定义命令和远程 app-server 排除在该软件包检查之外。

在基于此构建之前，有一个值得了解的矛盾。OpenAI 自己的 app-server 文档指出：“app-server 命令和 WebSocket 传输是实验性的，不支持生产工作负载”——请注意，该警告同时提到了命令和传输。OpenClaw 在此命令之上构建了一个已发布的功能，其 transport 字段默认为 stdio；只有在配置 url 时才使用 websocket。两种说法可以同时成立；请结合两者作出决定。

委派产物、权限、取消和恢复

Harness 文档坦诚说明了原生子代理状态能够证明的范围：执行、任务结果和结果交付是彼此独立的事实；处于空闲、被中断或已卸载状态的原生线程不能证明任务成功；当无法获得接近完成的确认时，任务会要求你重试关闭。原生 Codex 子代理是 Codex 自身的机制——显式的 OpenClaw 或 ACP 委派仍会通过 sessions_spawn。

根据插件配置字段表，app-server 为 OpenClaw 启动的执行权限默认使用模式 yolo、审批策略 never 和沙箱 danger-full-access；除非本地 Codex 要求不允许这种设置，此时 guardian 默认更倾向于按请求审批，并使用 workspace-write，否则使用 read-only；requestTimeoutMs是 app-server 控制平面调用的超时时间，默认为 60000。这些是 OpenClaw 为其启动的进程设置的默认值，而不是 Codex CLI 自身的默认值；对于不熟悉的代码仓库，首次运行前应先检查第一个默认设置。

回合期间的控制是原生的：/codex stop、/codex steer、/codex resume、/codex detach、/codex bind、/codex compact、/codex threads、/codex goal、/codex model、/codex fast 和 /codex permissions。受限回合是按回合设置的，而不是会话模式；它只对该回合禁用原生 Code Mode、环境选择、已配置的 MCP 服务器和原生钩子中继。OpenClaw 的 运行时 v1 支持契约还列出了不支持的功能：原生工具参数修改（预工具钩子可以阻止执行，但 OpenClaw 不会重写参数）、可编辑的 Codex 原生转录历史、压缩干预，以及逐字节的模型 API 请求捕获。因此，如果你的审计要求是获得确切的出站请求，此运行时无法提供。

授权、计划权益和令牌消耗是三件不同的事

于 2026 年 9 月 21 日读取自OpenClaw 的 Codex app-server 策略页面。这里还有一个名称陷阱：OpenAI 的 API 定价页面称 Priority processing 已于 2026 年 7 月 30 日更名为 Fast mode，并且你可以发送 service_tier，其值为 "priority" 或 "fast"；而 OpenClaw 的 appServer.serviceTier记录的是 "priority" 和 "flex"，并将旧版 "fast" 规范化为 "priority"——方向相反。在两个系统中，“开启快速模式”意味着不同的事情。

为什么第三方端点会使请求脱离 harness

这是大多数第三方文章弄反的单一事实。对于提供商或模型运行时未设置或为 auto 的情况，OpenClaw 的隐式代理运行时表规定：

因此，将 OpenClaw 指向任何第三方 base URL——包括 Kunavo——都会按设计让该回合使用 OpenClaw 的内置运行时。仅有 openai/* 前缀绝不会选择 harness，强制设置 agentRuntime.id: "codex" 也无法挽救这一点。运行时页面称该设置“要求已注册的 Codex harness；不支持的路由或身份验证会安全失败，但编写者指定的请求覆盖可以在执行前使用 Codex 声明的精确请求 OpenClaw 回退”——因此结果只有两种：回合失败，或执行 OpenClaw 回合；两者都不是在自定义端点上运行 Codex。插件的文档化配置字段也没有模型 base-URL 设置；其中唯一的 url 字段是 app-server 自己的 WebSocket 或 unix:// 地址。appServer.args 是否能够将提供商覆盖偷偷传入受管理的 app-server，文档没有说明，也未经测试；本页不将其作为变通方案。

内置运行时路由还会重塑请求，而OpenClaw 的自定义提供商页面明确规定了每条规则的适用范围。对于非原生端点上的 api: "openai-completions"——其定义为任何非空的 baseUrl，且主机不是 api.openai.com——OpenClaw 会强制将 compat.supportsDeveloperRole设为 false，并覆盖显式的 true。此外，代理式 OpenAI 兼容路由“跳过原生的仅限 OpenAI 的请求塑形”：没有 service_tier，没有 Responses store，没有 Completions store，没有提示缓存提示，没有 OpenAI 推理兼容载荷塑形，也没有隐藏的归属标头。由于线路上没有 service_tier，此类路由无法选择 Fast mode 和 Flex。该页面提供的替代方案是为 OpenAI 兼容的 Completions 代理透传 params.extra_body、按提供商设置 headers，以及为慢速或远程主机设置 models.providers.<id>.timeoutSeconds。

Codex 自身是另一半，而且限制更宽松：Codex 的高级配置页面显示，~/.codex/config.toml支持使用 base_url 和 env_key配置 [model_providers.<id>]。但存在硬性门槛——配置参考指出，对于 model_providers.<id>.wire_api，“responses 是唯一受支持的值；省略时它也是默认值”。因此，仅提供 Chat Completions 的端点无法驱动 Codex。同一高级配置页面保留了内置 ID openai、ollama 和 lmstudio，并将 model_provider 和 model_providers列为 Codex 在项目级 .codex/config.toml 中会忽略的键，因此提供商键应放在用户级配置中。Kunavo 在 /v1/responses提供原生 Responses 界面，这使Codex CLI 配置成为可能——但那是独立的 Codex CLI，而不是 OpenClaw harness；Kunavo 尚未对任一客户端进行运行时测试。

软件成本与令牌成本

OpenClaw 本身为 $0。其文档索引将该项目描述为 MIT 许可、由社区驱动、由独立的 501(c)(3) 基金会开发，并注明“无付费层级”；@openclaw/codex在公共 npm 注册表上免费发布。所有实际成本都来自运行 Gateway 的机器和模型用量，而模型用量通过三种合同之一产生。

根据 OpenAI 的Codex 定价页面，于 2026 年 9 月 21 日核查。该表还需结合三个注意事项。定价卡只为 Pro 发布了“$100 起”的价格；OpenAI 单独的关于 ChatGPT Pro 层级文章列出了更高的 $200 层级，但截至 2026 年 9 月 10 日，该层级的新用户注册和升级已暂停，因此应在结账时确认，而不要以本页未在定价卡上看到的数字编制预算。包含的用量仅以每五小时内本地消息数量的估算范围发布，而不是固定消息数量。包含额度用尽后的积分费率以每百万令牌的积分数发布，而该定价页面没有提供每个积分的美元价值，因此没有为该行提供美元换算。此外，GPT-5.5 将于 2026 年 10 月 14 日从所有计划的 ChatGPT、ChatGPT Work 和 Codex 中退役，但 OpenAI API 不受影响。

第三种合同是 OpenClaw 内置运行时上的 Gateway。假设一次委派回合发送180,000 个未缓存输入令牌并接收9,000 个输出令牌；费率采用实时的Kunavo 目录每百万令牌价格。

这些是说明性令牌计算，不是实测任务成本，也不是账单上限——回合形状是一个假设，而真实 agent 回合会在每次工具往返中重新发送上下文。Kunavo 目录金额是计费下限而非上限：上游报告费用后，账单取目录成本与上游成本乘以适用加价两者中的较高值。缓存费用和外部工具不包含在示例中。最低充值金额是预付余额中的 $10；它为余额充值，而不是购买计划——请参阅账单详情。

Kunavo 不提供嵌入模型、文本转语音模型或语音转文本模型。这些步骤在任何路由上都不由 Kunavo 提供，因此应将其交给提供这些能力的提供商。

这里的边界很重要，因为上面的界面表将非代理的 OpenAI Platform 路由与 harness 分开，而 Gateway 密钥只覆盖 Kunavo 目录中的聊天模型。

哪种路由胜出时

如果答案是 Gateway 这一行，请从Codex CLI 集成开始了解 Responses API 形式，在OpenClaw 最佳 API和Codex 最佳 API中比较选项，并在准备为密钥充值时创建 Kunavo 账户。关于自托管助手的预算问题，OpenClaw 定价会分别列出软件、托管和模型支出。

常见问题

上面的运行时表、身份验证顺序、app-server 警告、wire_api门槛、版本固定值和计划价格，均于 2026 年 9 月 21 日从 OpenClaw 和 OpenAI 自有文档、OpenAI 帮助中心，以及 openclaw、@openclaw/codex、@openai/codex、codex 和 openclaw-code-agent 的 npm 注册表条目获取。每条声明都链接到其来源页面；对于文档未解决的问题，文本会明确说明，而不会填补空白。Kunavo 未对 OpenClaw 或 Codex harness 进行任何运行时测试，因此这里的每项配置都是根据源文档核查，而不是针对 Kunavo 端点验证。Kunavo 令牌费率来自实时目录，每个美元数字均为说明性计算。