Codexharness故障排除

Codex 应用程序服务器harness的症状、原因和修复。 Codex harness 指南的一部分； 每个部分移动的位置 列出每个部分。

故障排查

Codex 不会作为普通的 /model 提供方出现： 对于新配置来说这是预期行为。请选择 openai/gpt-* 模型，启用 plugins.entries.codex.enabled，并检查 plugins.allow 是否排除了 codex。

OpenClaw 使用内置harness而不是 Codex： 确认有效路由是确切的官方 HTTPS 平台响应或 ChatGPT 响应路由，没有编写的提供程序请求覆盖，并且 Codex 插件是安装并启用。肯定推理支持和本机推理工作元数据不计为请求覆盖。标头、请求参数、超时和有效负载兼容性开关仍然有效：Codex 声明 OpenClaw 后备，保留确切的请求，包括显式运行时选择。其他不受支持的 routes/authentication 和缺少显式harness会停止执行并出现错误。 openai/gpt-* 前缀和 agentRuntime.id: "codex" 本身并不是执行证明；检查完成结果中的实际harness。请参见运行时选择。

OpenAI Codex runtime 回退到 API-key 路径： 收集一段已脱敏的 gateway 摘录，展示 model、runtime、所选 provider 和失败信息。请受影响的协作者在其 OpenClaw 主机上运行以下只读命令：

(  pattern='openai/gpt-5\.[45]|openai[-]codex|agentRuntime(\.id)?|harnessRuntime|Runtime: OpenAI Codex|legacy OpenAI Codex prefix|resolveSelectedOpenAIRuntimeProvider|candidateProvider[": ]+openai|status[": ]+401|Incorrect API key|No API key|api-key path|API-key path|OAuth'   if ls /tmp/openclaw/openclaw-*.log >/dev/null 2>&1; then    grep -E -i -n "$pattern" /tmp/openclaw/openclaw-*.log 2>/dev/null || true  else    journalctl --user -u openclaw-gateway --since today --no-pager 2>/dev/null \      | grep -E -i "$pattern" || true  fi) | sed -E \    -e 's/(Authorization: Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(api[_ -]?key[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/(OPENAI_API_KEY[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/sk-[A-Za-z0-9_-]{12,}/sk-[REDACTED]/g' \    -e 's/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/[EMAIL-REDACTED]/g' \  | tail -200

有用的摘录通常包括 openai/gpt-6-astra 或 openai/gpt-5.6-luna、Runtime: OpenAI Codex、agentRuntime.id 或 harnessRuntime、candidateProvider: "openai" 以及 401、Incorrect API key 或No API key 结果。更正后的运行应显示 OpenAI OAuth 路径，而不是普通的 OpenAI API-key 故障。

旧版 Codex 模型引用配置仍然存在： 运行 openclaw doctor --fix。Doctor 会将旧版模型引用重写为 openai/*，移除过期的会话和整 agent runtime 固定配置，并保留现有的 auth-profile 覆盖。

应用程序服务器被拒绝： 使用 Codex 0.149.0 或更新版本。较旧的、格式错误的和未版本化的服务器将被拒绝。较新的语义版本继续针对 Codex 版本 OpenClaw 提供兼容性警告和正常运行时验证。更新或删除选择其他版本的自定义、远程或桌面二进制覆盖。

/codex status 无法连接： 检查 codex 插件是否已启用；如果配置了 allowlist，检查 plugins.allow 是否包含它；并确认任何自定义的 appServer.command、url、authToken 或 headers 都有效。

无法解析应用程序服务器消息： OpenClaw 在其他有效的 JSON 字符串中恢复原始换行符。无效的转义或未转义的控制字符会产生经过编辑的警告，然后在 Node 和 Bun 上继续解码并显示下一条消息。这些无效片段不会消耗后续的有效消息。

驻留目录报告生成失败： 缺少可执行文件 （ENOENT）、缺少执行权限 （EACCES） 或不兼容的 CPU （EBADARCH，有时显示为 macOS errno -86） 停止该目录的自动重试并记录一个建议。这包括 Node 和 Bun 上的本机启动错误，这些错误的诊断是在注册或初始化期间托管启动器退出后到达的。修复安装，然后重新启动网关以重试。不相关的配置重新加载不会重试失败的可执行文件。通过配置重新加载禁用插件会终止其目录刷新循环。

托管被动目录使用插件安装的 Codex 包，并且不会回退到 macOS 桌面应用程序包。 OpenClaw 使用网关的解释器运行其启动器，因此 Codex 选择与该解释器架构匹配的平台包，而无需 node PATH 查找。在调试或跟踪日志级别，Codex app-server spawn 记录可执行文件、启动程序和解析的本机二进制路径，无需参数或凭据。在 macOS 上使用 file <path> 来检查失败的可执行文件的体系结构。使用 openclaw doctor --lint --only codex/managed-app-server --json 检查托管本机二进制文件，包括仅为其会话目录启用 Codex 时。

名为 openclaw-model-catalog-* 的目录包含 OpenClaw 插件源捕获，而不是本机 Codex 会话。目前的捕获量受到工人世代的限制，并与工人一起退休。医生通过离线清理命令报告称，较年长的捕获物处于托管监管之外；它不会自动删除那些旧目录。

Codex app-server 使用过多内存： 首先区分这两个进程。 OpenClaw 将本地 Codex app-server 作为独立的 Rust 子进程运行。 NODE_OPTIONS=--max-old-space-size=... 只会改变 Gateway 的 Node.js V8 堆大小；它不会限制或扩大 Codex 的内存。受管控的 Gateway 安装已经会选择自适应的 V8 堆大小， 增大该值反而可能为 Codex 留下更少的主机内存。对于 Gateway 内存压力，请使用 Gateway 内存故障排查， 并检查主机或容器为 Codex 子进程分配的内存。

大型目录回复使用网关中的解码器工作人员。完成回复后，OpenClaw 一分钟后释放该工作人员，无需进一步工作人员解码。本机应用程序-服务器连接及其温暖对话线程保持连接。稍后的大型回复会启动新的解码器，因此其第一次响应可能需要更长的时间；小回复不需要工人。不完整的回复将保留其解码器，直到恢复完成或连接关闭。

**“无法检查Codex流程”：**此错误来自模型推理之前的本地流程检查。对于截止时间错误，请在主机响应恢复后重试。对于权限错误，请检查对 Linux 上的 /proc 或 macOS 上的 ps 的访问。

网关重新启动后清理过程中新一轮失败： OpenClaw 在开始替换之前检查已注册的 Codex 进程。已退出的进程或PID已被重用的进程的注册将被自动删除，而无需扫描不相关的进程。启动清理和新连接会串行化恢复，因此它们无法同时停止或恢复同一孤立连接。在替换工作开始之前，实时孤立进程仍然需要经过验证的后代清理。如果清理仍然受阻，请检查网关日志和主机进程检查访问；不要删除进程注册来绕过恢复。

捆绑的 Codex 没有堆或 RSS 限制，也没有可配置的空闲卸载延迟。在最后一个客户端取消订阅后， 非活跃线程最多可以保持加载 30 分钟。OpenClaw 会在每个 Codex app-server 上独立保持最多 64 个空闲会话线程的订阅， 在它们最后一次活动后的 30 分钟内持续如此。当多个会话交替使用时，这可以保留热会话和会话范围的审批。 活跃轮次以及拥有未完成原生子 agent 的父线程会受到保护，不会被空闲回收；会话重置或删除会立即释放其自身线程。 达到空闲上限后，会取消订阅最近最少使用的会话；随后 Codex 会应用其独立的卸载延迟， 之后恢复的会话可能需要再次进行审批。

在资源受限的主机上，请先减少原生 Codex 子 agent 的扇出，再增加 Gateway 堆大小：

{  plugins: {    entries: {      codex: {        config: {          appServer: {            args: ["-c", "agents.max_threads=3", "app-server", "--listen", "stdio://"],          },        },      },    },  },}

该设置限制捆绑的 Codex 默认多代理后端的本机子线程。如果您显式启用 Codex 多代理 v2，请改用 features.multi_agent_v2.max_concurrent_threads_per_session=3； v2 限制包括根线程，不能与 agents.max_threads 组合。要获得更多 Codex 余量，请增加主机、容器或 cgroup 内存分配。 OS 硬限制可以终止 Codex 而不是对其进行反压。

模型发现速度慢： 检查应用程序服务器与其模型目录端点的连接。默认 plugins.entries.codex.config.discovery.timeoutMs 为 10 秒，因此 Codex 可以完成其本机刷新或回退。较短的覆盖可能会中断回退并使本机模型不可用。请参阅 Codex harness参考 。

Codex 插件状态已达到其行限制： 运行 openclaw doctor 以检查已删除或过期的 OpenClaw 会话留下的绑定。停止网关，然后运行 ​​openclaw doctor --fix 以在会话修复后删除经过验证的孤立会话绑定。 Doctor 保留受监督的绑定、有效租约、不明确的所有权以及无法读取会话存储的绑定。此清理不会删除本机 Codex 线程历史记录或托管线程咨询记录。

WebSocket 传输立即失败： 检查 appServer.url、 authToken、headers，并确认远程 app-server 使用相同的 Codex app-server 协议版本。Codex WebSocket 传输仍处于实验阶段且不受支持； 优先使用受管控的 stdio 或本地 Unix 控制套接字。

原生 shell 或 patch 工具被 Native hook relay unavailable 阻止： Codex 线程仍在尝试使用 OpenClaw 已不再注册的原生 hook relay id。这是原生 Codex hook 传输问题，不是 ACP 后端、provider、GitHub 或 shell 命令失败。请在受影响的聊天中使用 /new 或 /reset 开启全新会话， 然后重试一个无害命令。如果这次能成功，但下一次原生工具调用又失败， 则将 /new 仅视为临时解决方案：在重启 Codex app-server 或 OpenClaw Gateway 之后，将提示复制到新会话中，以便旧线程被丢弃并重新创建原生 hook 注册。

Codex 工具调用创建了太多短期挂钩进程： 设置 plugins.entries.codex.config.appServer.loopDetectionPreToolUseRelay: false 并重新启动网关。这仅禁用用于 OpenClaw 循环检测的 Codex PreToolUse 子进程及其无策略标记。所需的 before_tool_call 和可信工具策略中继保持启用状态。

非 Codex 模型使用内置 harness： 除非 provider 或 model runtime policy 将其路由到其他 harness，否则这是预期行为。 普通的非 OpenAI provider 引用在 auto 模式下仍会使用其正常的 provider 路径。

Computer Use 已安装但工具无法运行： 在新的会话中检查 /codex computer-use status。如果某个工具报告 Native hook relay unavailable， 请使用上面的原生 hook relay 恢复方法。 参见 Codex Computer Use。