故障排除
Codex 应用服务器 harness 的症状、原因和修复方法。属于 Codex harness 指南的一部分;各章节迁移位置 列出了每个章节。
故障排查¶
Codex 不会作为普通的 /model provider 出现: 这在新的配置中属于预期行为。请选择一个 openai/gpt-* 模型,启用 plugins.entries.codex.enabled,并检查 plugins.allow 是否排除了 codex。
OpenClaw 使用内置 harness 而不是 Codex: 请确认生效路由是一条精确的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由,没有自定义的 provider 请求覆盖,并且 Codex 插件已安装并启用。明确支持推理和原生 reasoning-effort 元数据不算作请求覆盖。Headers、请求参数、超时设置以及 payload 兼容性开关仍然算作请求覆盖:Codex 声明了一个 OpenClaw 回退机制,该机制会保留精确的请求,包括针对显式运行时选择的情况。其他不支持的路由/认证方式以及缺少显式 harness 的情况会以 fail-closed 的方式失败。仅凭 openai/gpt-* 前缀和 agentRuntime.id: "codex" 并不能证明实际执行;请在完成结果中检查实际的 harness。参见 运行时选择。
OpenAI Codex 运行时回退到 API-key 路径: 请收集一份经过脱敏的 gateway 摘录,其中应显示模型、运行时、所选 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 的运行时锁定,并保留现有的 auth-profile 覆盖。
应用服务器被拒绝: 请使用 Codex 0.149.0 或更高版本。较旧、格式错误以及未标注版本的服务器会被拒绝。较新的语义化版本会继续运行,但附带兼容性警告,并针对 OpenClaw 自带的 Codex 版本进行正常的运行时验证。请更新或移除选择其他版本的自定义、远程或桌面二进制覆盖。
/codex status 无法连接: 请检查 codex 插件是否已启用,在配置了允许列表时 plugins.allow 是否包含它,以及任何自定义的 appServer.command、url、authToken 或 headers 是否有效。
无法解析应用服务器消息: OpenClaw 会恢复在其他方面有效的 JSON 字符串中的原始换行符。无效的转义或未转义的控制字符会产生一条脱敏警告,随后在 Node 和 Bun 上都会从下一条消息恢复解码。这些无效片段不会消耗后续的有效消息。
常驻目录报告 spawn 失败: 可执行文件缺失(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 应用服务器占用内存过多: 请先区分这两个进程。OpenClaw 将本地 Codex 应用服务器作为独立的 Rust 子进程运行。NODE_OPTIONS=--max-old-space-size=... 只会改变 Gateway 的 Node.js V8 堆大小;它不会限制或扩大 Codex。受管 Gateway 安装已选择自适应 V8 堆,提高它可能会给 Codex 留下更少的主机内存。对于 Gateway 压力,请参见 Gateway 内存故障排查,并检查主机或容器中 Codex 子进程的内存占用。
大型目录回复在 Gateway 中使用解码器工作线程。完整回复后,如果在一分钟内没有进一步的工作线程解码,OpenClaw 会释放该工作线程。原生应用服务器连接及其温会话线程保持连接。后续的大型回复会启动新的解码器,因此其首个响应可能耗时更长;小型回复不需要工作线程。未完成的回复会保留其解码器,直到恢复完成或连接关闭。
“无法检查 Codex 进程”: 此错误来自模型推理之前的本地进程检查。如果是超时错误,请在主机响应恢复后重试。如果是权限错误,请检查 Linux 上对 /proc 的访问权限或 macOS 上的 ps。
网关重启后的清理期间新回合失败: OpenClaw 在启动替换进程之前会检查已注册的 Codex 进程。对于已退出或 PID 已被复用的进程,其注册会被自动移除,而无需扫描不相关的进程。启动清理和新连接会将恢复操作序列化,因此它们无法同时停止或恢复同一个孤立进程。存活的孤立进程仍需要经过验证的后代清理后,才能开始替换工作。如果清理仍然受阻,请检查 Gateway 日志和主机进程检查访问权限;不要删除进程注册以绕过恢复。
内置 Codex 没有堆或 RSS 限制,也没有可配置的空闲卸载延迟。在最后一个客户端取消订阅后,不活跃的线程最多可保持加载 30 分钟。OpenClaw 会独立地在每个 Codex 应用服务器上,将最多 64 个空闲会话线程在其最后一次活动后保持订阅 30 分钟。这可在多个对话交替时保留温会话和会话级审批。活跃回合和带有未完成原生子代理的父线程受保护,不会被空闲驱逐;会话重置或删除会立即释放其自身线程。空闲限制驱逐会取消订阅最近最少使用的会话,之后 Codex 会应用其单独的卸载延迟,稍后恢复的会话可能需要重新审批。
在资源受限的主机上,先减少原生 Codex 子代理扇出,再增加 Gateway 堆内存:
{
plugins: {
entries: {
codex: {
config: {
appServer: {
args: ["-c", "agents.max_threads=3", "app-server", "--listen", "stdio://"],
},
},
},
},
},
}
该设置限制了内置 Codex 默认多代理后端的原生子线程。如果你显式启用 Codex multi-agent v2,请改用 features.multi_agent_v2.max_concurrent_threads_per_session=3;v2 限制包括根线程,且不能与 agents.max_threads 组合使用。若要为 Codex 获得更多余量,请增加主机、容器或 cgroup 的内存分配。操作系统硬限制可能会终止 Codex,而不是对其施加背压。
模型发现缓慢: 检查应用服务器到其模型目录端点的连接。默认的 plugins.entries.codex.config.discovery.timeoutMs 为 10 秒,以便 Codex 完成其原生刷新或回退。较短的覆盖值可能会中断该回退,并使原生模型不可用。参见 Codex harness 参考。
Codex 插件状态已达到其行数上限: 运行 openclaw doctor 检查已删除或过期的 OpenClaw 会话留下的绑定。停止 Gateway,然后在会话修复后运行 openclaw doctor --fix 移除已被证实的孤立会话绑定。Doctor 会保留受监管的绑定、活跃租约、所有权不明确的绑定,以及无法读取其会话存储的绑定。此清理不会删除原生 Codex 线程历史或受管线程建议记录。
WebSocket 传输立即失败: 检查 appServer.url、authToken、请求头,并确认远程应用服务器使用相同的 Codex 应用服务器协议版本。Codex WebSocket 传输仍处于实验阶段且不受支持;请优先使用受管 stdio 或本地 Unix 控制套接字。
原生 shell 或补丁工具因 Native hook relay unavailable 而被阻止: Codex 线程仍在尝试使用 OpenClaw 不再注册的原生 hook 中继 ID。这是原生 Codex hook 传输问题,不是 ACP 后端、provider、GitHub 或 shell 命令故障。在受影响的聊天中通过 /new 或 /reset 启动新会话,然后重试一个无害命令。如果这能成功一次,但下一次原生工具调用再次失败,请仅将 /new 视为临时解决措施:在重启 Codex 应用服务器或 OpenClaw Gateway 后,将提示词复制到新会话中,以便丢弃旧线程并重新创建原生 hook 注册。
Codex 工具调用创建了太多短时存活的 hook 进程: 设置 plugins.entries.codex.config.appServer.loopDetectionPreToolUseRelay: false 并重启 Gateway。这只会禁用用于 OpenClaw 循环检测的 Codex PreToolUse 子进程及其无策略标记。必需的 before_tool_call 和受信工具策略中继保持启用。
非 Codex 模型使用内置 harness: 这是预期行为,除非 provider 或模型运行时策略将其路由到另一个 harness。在 auto 模式下,普通的非 OpenAI provider 引用保持在它们正常的 provider 路径上。
Computer Use 已安装但工具无法运行: 在新会话中检查 /codex computer-use status。如果某个工具报告 Native hook relay unavailable,请使用上面的原生 hook 中继恢复方法。参见 Codex Computer Use。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw