故障排除

Codex app-server harness 的症状、原因和修复方法。属于 Codex harness 指南的一部分；各章节移动位置 列出了每个章节。

故障排查¶

Codex 未显示为普通的 /model 提供商： 对于新配置，这是预期行为。请选择一个 openai/gpt-* 模型，启用 plugins.entries.codex.enabled，并检查 plugins.allow 是否排除了 codex。

OpenClaw 使用内置 harness 而不是 Codex： 请确认生效的路由是精确的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由，没有已编写的提供商请求覆盖，并且 Codex 插件已安装并启用。肯定推理支持和原生 reasoning-effort 元数据不计为请求覆盖。请求头、请求参数、超时和 payload 兼容性开关仍会构成请求覆盖：Codex 声明了一个 OpenClaw 回退机制，它会保留精确的请求，包括显式运行时选择的情况。其他不受支持的路由/身份验证以及缺失的显式 harness 会失败关闭。仅凭 openai/gpt-* 前缀和 agentRuntime.id: "codex" 并不能证明实际执行；请检查已完成结果中的实际 harness。参见 运行时选择。

OpenAI Codex 运行时回退到 API-key 路径： 请收集一份已脱敏的 Gateway 摘录，其中显示模型、运行时、所选提供商和失败情况。请受影响的协作者在其 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 运行时固定项，并保留现有的 auth-profile 覆盖。

app-server 被拒绝： 请使用 Codex 0.149.0 或更高版本。较旧、格式错误和未带版本号的服务器会被拒绝。较新的语义版本会继续运行，并带有兼容性警告，同时针对 OpenClaw 随附的 Codex 版本执行正常的运行时验证。更新或移除选择其他版本的自定义、远程或桌面二进制覆盖。

/codex status 无法连接： 请检查 codex 插件是否已启用，当配置了允许列表时 plugins.allow 是否包含它，以及任何自定义 appServer.command、url、authToken 或请求头是否有效。

无法解析 app-server 消息： OpenClaw 会恢复其他方面有效的 JSON 字符串中的原始换行符。无效转义或未转义的控制字符会产生一条已脱敏的警告，然后在 Node 和 Bun 上都会从下一条消息恢复解码。这些无效片段不会消耗后续的有效消息。

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

托管被动目录使用插件已安装的 Codex 包，不会回退到 macOS 桌面应用包。OpenClaw 使用 Gateway 的解释器运行其启动器，因此 Codex 会选择与该解释器架构匹配的平台包，而无需进行 node PATH 查找。在 debug 或 trace 日志级别下，Codex app-server spawn 会记录可执行文件、启动器和已解析的原生二进制路径，但不包含参数或凭据。在 macOS 上使用 file <path> 检查失败可执行文件的架构。使用 openclaw doctor --lint --only codex/managed-app-server --json 检查托管原生二进制文件，包括 Codex 仅为其会话目录启用的情况。

名为 openclaw-model-catalog-* 的目录包含 OpenClaw 插件源捕获，而不是原生 Codex 会话。当前捕获受 worker 代际限制，并随其 worker 一起退役。Doctor 会报告托管范围之外的旧捕获，并提供一个离线清理命令；它不会自动删除这些遗留目录。

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 子进程的主机或容器内存。

大型目录回复会在 Gateway 中使用解码器工作进程。在完整回复后，OpenClaw 会在没有进一步工作进程解码的一分钟后释放该工作进程。原生 app-server 连接及其预热会话线程保持连接。后续的大型回复会启动新的解码器，因此其首次响应可能耗时更长；小型回复不需要工作进程。不完整回复会保留其解码器，直到恢复完成或连接关闭。

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

Gateway 重启后清理期间新回合失败： OpenClaw 在启动替代进程前会检查已注册的 Codex 进程。对于已退出或 PID 已被重用的进程，其注册信息会自动移除，而不会扫描无关进程。启动清理和新连接会串行化恢复过程，因此它们无法并发停止或恢复同一个孤儿进程。存活的孤儿进程在开始替代工作前仍需要经验证的子代清理。如果清理仍然被阻塞，请检查 Gateway 日志和主机进程检查访问权限；不要删除进程注册信息以绕过恢复。

捆绑的 Codex 没有堆或 RSS 限制，也没有可配置的闲置卸载延迟。最后一个客户端取消订阅后，非活动线程最多可保持加载状态 30 分钟。OpenClaw 会独立地在每个 Codex app-server 上，于其最后活动后保持最多 64 个空闲会话线程处于订阅状态 30 分钟。当多个会话交替时，这会保留预热会话和会话范围的审批。活动回合以及具有未完成原生子代理的父级会受到保护，免于闲置驱逐；会话重置或删除会立即释放其自身线程。闲置限制驱逐会取消订阅最近最少使用的会话，之后 Codex 会应用其独立的卸载延迟，稍后恢复的会话可能再次需要审批。

在资源受限的主机上，请先减少原生 Codex 子代理的扇出，再增加 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 内存分配。操作系统硬限制可能会终止 Codex，而不是对其施加背压。

模型发现缓慢： 请检查 app-server 到其模型目录端点的连接性。默认 plugins.entries.codex.config.discovery.timeoutMs 为 10 秒，以便 Codex 完成其原生刷新或回退。更短的覆盖值可能会中断该回退，并使原生模型不可用。参见 Codex 测试框架参考。

Codex 插件状态已达到行数限制： 运行 openclaw doctor 以检查由已删除或已过期的 OpenClaw 会话遗留的绑定。停止 Gateway，然后运行 openclaw doctor --fix，在会话修复后移除已证实的孤儿会话绑定。Doctor 会保留受监督的绑定、活动租约、所有权不明确以及无法读取其会话存储的绑定。此清理不会删除原生 Codex 线程历史或受管线程建议记录。

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

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

Codex 工具调用创建过多短生命周期的 hook 进程： 设置 plugins.entries.codex.config.appServer.loopDetectionPreToolUseRelay: false 并重启 Gateway。这只会禁用用于 OpenClaw 循环检测及其无策略标记的 Codex PreToolUse 子进程。必需的 before_tool_call 和受信任工具策略中继仍保持启用。

非 Codex 模型使用内置测试框架： 除非 provider 或模型运行时策略将其路由到另一个测试框架，否则这是预期行为。普通非 OpenAI provider 引用在 auto 模式下会保持在其正常 provider 路径上。

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