Codex 常见错误与解决方法

搜索错误信息、错误码或关键词，查看原因和处理步骤。

共 19 项常见错误

模型容量不足

服务端
Selected model is at capacity.
codex_error_info: server_overloaded

模型服务暂时无法处理请求。这个错误不等于 Usage Limit，不能据此判断个人额度已用完。

解决方法
  1. 先保存任务进度，再切换可用模型或稍后重试，并查看 OpenAI 服务状态。
  2. 若新线程正常、旧线程持续失败，用交接摘要开启新线程。所有模型持续失败时，用 /feedback 提交时间、版本和错误类型。

在 Codex CLI 中切换模型

/model
查看 OpenAI 服务状态
个案报告 · Capacity · #46798

额度或账户权益异常

账户与额度
You've hit your usage limit. UsageLimitExceeded

请求被额度或账户权益限制；需要核对登录方式、账户和用量窗口。

解决方法
  1. 检查当前账户、workspace 和用量页面的 5 小时／每周恢复时间。
  2. 如果页面仍显示有额度，保存任务后重新登录正确账户；持续不一致时保留脱敏截图和发生时间。

API Key 使用 OpenAI Platform 计费与额度，不消耗 ChatGPT 套餐内的 Codex 权益；自定义 provider 还需检查其自身规则。

检查登录状态

codex login status

ChatGPT 登录失效时重新认证

codex logout
codex login

会退出当前登录，执行前保存任务。API Key 用户应先检查密钥与接口地址。

官方资料 · 身份验证

OAuth 回退到 dummy

身份验证
401 Unauthorized: Incorrect API key provided: dummy

若使用 ChatGPT 登录，这与已报告的 OAuth 状态异常相符，尤其是在切换网络之后。

解决方法
  1. 先确认登录方式。ChatGPT 用户优先重新认证，无需因为 dummy 去创建 API Key。
  2. 若使用自定义 provider 或 API Key，检查提供方认证配置；dummy 也可能是本地占位值。

检查登录状态

codex login status

ChatGPT 登录失效时重新认证

codex logout
codex login

会退出当前登录，执行前保存任务。API Key 用户应先检查密钥与接口地址。

官方资料 · 身份验证个案报告 · OAuth / dummy · #37192

认证失败 · 401

身份验证
401 Unauthorized

凭据可能过期、账户不匹配，或请求发往了不匹配的 provider。

解决方法
  1. 检查登录状态和目标 provider，确认使用 ChatGPT 登录还是 API Key。
  2. ChatGPT 用户可保存任务后退出并重新登录；API Key 用户检查密钥状态、所属组织和接口地址。

API Key 使用 OpenAI Platform 计费与额度，不消耗 ChatGPT 套餐内的 Codex 权益；自定义 provider 还需检查其自身规则。

检查登录状态

codex login status

ChatGPT 登录失效时重新认证

codex logout
codex login

会退出当前登录，执行前保存任务。API Key 用户应先检查密钥与接口地址。

官方资料 · 身份验证

反复重连或流式中断

网络与传输
Reconnecting... 1/5
stream disconnected before completion

连接中断可能来自网络、代理、客户端或服务端，单凭 reconnect 无法确定根因。

解决方法
  1. 运行 Doctor，检查 VPN、代理、DNS、防火墙和自定义 CA；再用手机热点做对照。
  2. 在同一账户和网络下比较 CLI 与 Desktop。如果都失败，继续检查服务状态和自定义 provider。

诊断连接与安装

codex doctor --summary

需要已安装 Codex CLI；旧版本不支持 Doctor 时先检查 codex --help。

查看 OpenAI 服务状态
官方资料 · Doctor 源码官方资料 · 配置优先级

WebSocket 连接超时

网络与传输
Responses WebSocket timed out

WSS 握手或传输未完成，需要检查 WebSocket 通行策略和网络路径。

解决方法
  1. 先运行 Doctor，再用其他网络对照，确认代理或防火墙允许 WSS。
  2. 若只有当前网络失败，检查 DNS、证书及 IPv4／IPv6 路由；不要把永久关闭 IPv6 当作默认修复。

诊断连接与安装

codex doctor --summary

需要已安装 Codex CLI；旧版本不支持 Doctor 时先检查 codex --help。

查看 OpenAI 服务状态
官方资料 · Doctor 源码

自定义接口或本地代理失效

客户端与配置
Connection refused: http://127.0.0.1:8787/v1
openai_base_url

Codex 可能仍在连接旧的接口覆盖地址，或本地代理没有启动。

解决方法
  1. 在实际生效的用户配置中检查 openai_base_url、model_provider 和 provider 的 base_url。
  2. 确认地址和监听进程是否仍需要。备份配置后修正过期覆盖并重启；分享配置时先移除密钥和私有地址。

macOS / Linux · CODEX_HOME

printenv CODEX_HOME

未设置 CODEX_HOME 时默认使用用户目录下的 .codex。

Windows · PowerShell · CODEX_HOME

$env:CODEX_HOME
官方资料 · 配置优先级个案报告 · Base URL · #40435

上下文窗口已满

上下文
Context window exceeded.
Codex ran out of room in the model's context window.

线程、图片或工具输出占用了过多上下文；已满线程中的压缩也可能失败。

解决方法
  1. 用已保存的任务摘要开启新线程，先核对仓库状态，再继续未完成步骤。
  2. 以后按阶段更新 docs/codex-handoff.md，缩短工具输出，将长期规则放进 AGENTS.md。
个案报告 · Context / compaction · #43963官方资料 · AGENTS.md 指令

上下文压缩失败

上下文
Error running remote compact task

上下文压缩请求失败。查看同一段日志中的具体错误，例如 server_overloaded、context_window_exceeded 或连接超时。

解决方法
  1. 查看同段日志是否还有 server_overloaded、context_window_exceeded 或连接错误，按对应方向排查。
  2. 更新客户端；旧线程持续卡住时，从仓库和交接摘要恢复到新线程，不依赖反复 /compact。
个案报告 · Context / compaction · #43963

沙盒文件或网络权限

沙盒与 Git
Permission denied / Read-only file system

可写目录、命令联网权限与审批策略是不同设置，也可能存在操作系统文件权限限制。

解决方法
  1. 查看 /permissions 和实际工作目录，确认目标文件位于允许写入的范围。
  2. 聊天正常但安装依赖或 curl 失败时，检查命令的 network_access。只调整任务需要的权限。

在 Codex CLI 中查看权限

/permissions
官方资料 · 沙盒与审批

Git 元数据写入被拒绝

沙盒与 Git
fatal: Unable to create '.git/worktrees/feature/index.lock': Permission denied

.git 和 worktree 指向的 Git 目录可能受到额外只读保护，即使普通项目文件可写。

解决方法
  1. 检查仓库根目录、worktree 和 Git 状态，确认失败路径是否属于 Git 元数据。
  2. 代码编辑和测试完成后，为具体 Git 操作使用允许的审批方式，或在自己的终端完成提交。权限错误不能靠删除锁文件修复。

检查仓库状态

git rev-parse --show-toplevel
git status --short
git worktree list
官方资料 · 沙盒与审批

Git 锁文件已存在

沙盒与 Git
fatal: Unable to create '.git/index.lock': File exists. Another git process seems to be running.

可能有另一个 Git 进程正在操作仓库，也可能是先前中断留下的锁。

解决方法
  1. 检查 IDE、Git 客户端和终端是否有未结束的 Git 操作，先等待其完成。
  2. 只有确认没有 Git 进程且锁确实残留后，才手动处理对应锁文件；不要直接删除整个 .git。

检查仓库状态

git rev-parse --show-toplevel
git status --short
git worktree list
官方资料 · Git lockfile

MCP 工具或认证异常

MCP
Mcp error: -32603: Internal error

-32603 是通用内部错误，不能直接等同于 OAuth 失效；多个工具同时失败时可先检查认证。

解决方法
  1. 查看 MCP 服务是否启用、工具列表和认证状态。OAuth 服务可尝试重新执行 mcp login。
  2. 仍失败时检查服务所需环境变量、进程和服务端日志，再检查协议；不要把 Codex 主账户登录当作 MCP 登录。

查看 MCP 服务

codex mcp list

MCP OAuth 重新认证

codex mcp login SERVER_NAME

将 SERVER_NAME 替换为已配置的服务名称，仅适用于 OAuth 服务。

官方资料 · MCP 配置与认证个案报告 · MCP OAuth · #35344

配置修改未生效

客户端与配置

可能编辑了错误的 CODEX_HOME，项目不受信任，或配置被更高优先级覆盖。

解决方法
  1. 检查 /status、CODEX_HOME、CLI 参数和所选 profile；项目配置只在受信任项目中加载。
  2. 按 CLI → 项目 → profile → 用户 → 托管／系统 → 默认值核对。provider 与认证等设置还需核对是否允许项目级覆盖。

macOS / Linux · CODEX_HOME

printenv CODEX_HOME

未设置 CODEX_HOME 时默认使用用户目录下的 .codex。

Windows · PowerShell · CODEX_HOME

$env:CODEX_HOME
官方资料 · 配置优先级

AGENTS.md 指令未生效

项目使用方式

指令按目录逐层合并，靠近工作目录的文件可覆盖上层；合并长度也有上限。

解决方法
  1. 检查全局和当前目录路径上的 AGENTS.md、AGENTS.override.md；默认合并上限为 32 KiB。
  2. 修改后开启新会话，让 Codex 总结已加载的规则，确认工作目录和 CODEX_HOME 是否正确。

macOS / Linux · CODEX_HOME

printenv CODEX_HOME

未设置 CODEX_HOME 时默认使用用户目录下的 .codex。

Windows · PowerShell · CODEX_HOME

$env:CODEX_HOME
官方资料 · AGENTS.md 指令

更新后仍是旧版或找不到命令

客户端与配置
command not found: codex

PATH 中可能有多份安装，实际执行的二进制与刚更新的版本不同。

解决方法
  1. 比较版本与所有命令路径，检查 npm、Homebrew 和 standalone 是否同时安装。
  2. 确认当前主要安装方式后更新对应版本。npm EACCES 时检查安装目录归属，不要盲目使用 sudo 重装。

macOS / Linux

codex --version
command -v codex
type -a codex

Windows · PowerShell

codex --version
Get-Command codex -All
where.exe codex
个案报告 · PATH / updater · #25666官方资料 · Doctor 源码

Desktop／IDE 异常，CLI 正常

客户端与配置

同账户、网络和提示下，只有一个客户端失败时，应优先排查该客户端。

解决方法
  1. 完全退出并重开受影响客户端，更新后用新线程测试。
  2. 保留 CLI 对照结果、客户端版本和时间。Windows 扩展无响应时再检查原生运行库。

诊断连接与安装

codex doctor --summary

需要已安装 Codex CLI；旧版本不支持 Doctor 时先检查 codex --help。

官方资料 · Doctor 源码官方资料 · Windows 排查

Windows 沙盒或运行库异常

客户端与配置
Windows sandbox setup failed / VCRUNTIME140.dll missing

沙盒启动失败时查看 .sandbox/sandbox.log；扩展提示缺少 DLL 时，检查 C++ 运行库是否已安装。

解决方法
  1. 沙盒启动失败时重启 Codex，按官方说明检查 elevated／unelevated 模式及 .sandbox/sandbox.log。
  2. 扩展无响应或缺少 DLL 时检查 C++ Build Tools 和 x64 Redistributable。不要分享 .sandbox-secrets 内容。

诊断连接与安装

codex doctor --summary

需要已安装 Codex CLI；旧版本不支持 Doctor 时先检查 codex --help。

官方资料 · Windows 排查

Cloud 的 setup 与 agent 差异

项目使用方式

Setup 的联网权限和 secrets 不会自动延续到 agent 阶段；setup 中 export 的变量也不会自动传入 agent 的 shell。

解决方法
  1. Setup 可以联网安装依赖；agent 默认关闭互联网，需要在环境设置中按需开放。
  2. Secrets 只在 setup 提供。普通 export 不会跨 shell 保留，非敏感变量应使用环境配置；不要为了持久化而把 secret 写入仓库。
官方资料 · Cloud 环境

内容核对日期：2026-09-22

搜索在浏览器内完成，不上传或保存搜索内容。