OpenAI Codex CLI 认证、模型额度与 Remote Control 故障解决报告

OpenAI Codex CLI 认证、模型额度与 Remote Control 排障报告本文为公开脱敏版。文中的主机名、账号、会话 ID、设备码、配对码、具体服务器路径及精确时间均使用通用变量或占位符表示。一、环境与最终状态测试环境远程 Linux 服务器OpenAI Codex CLI standalone 安装使用 ChatGPT 账号通过设备码登录使用 Remote Control 连接远程设备本文统一使用以下路径变量exportCODEX_HOME$HOME/.codexexportCODEX_CLEAN_HOME$HOME/.codex-clean-test最终状态Codex 主认证正常 access token正常 refresh token正常 Codex Spark 模型可正常调用 默认高能力模型因额度耗尽暂时不可用 codex_apps已临时关闭 standalone 安装正常 Remote Control启动成功最终推荐配置model gpt-5.3-codex-spark cli_auth_credentials_store file [features] apps false如需信任特定项目目录可以另外添加[projects./path/to/project] trust_level trusted二、问题总览本次连续遇到了四类不同问题codex_apps启动时返回HTTP 401 token_revokedCodex 主登录的 refresh token 被撤销默认模型额度耗尽Remote Control 找不到 standalone Codex 安装这些问题互相独立不能只通过重复登录一次性解决。三、问题一codex_apps返回 HTTP 4013.1 错误表现Codex 启动时出现MCP client for codex_apps failed to start HTTP 401 Encountered invalidated oauth token for user code: token_revoked同时可能出现MCP startup incomplete (failed: codex_apps)3.2 错误含义失败的是 Codex 内置的 Apps/Connectors 集成层而不一定是主模型认证。codex_apps主要负责接入外部应用或托管连接器例如Google DriveSlackGitHub 连接器其他 ChatGPT Apps下面的命令显示没有自定义 MCPcodex mcp list可能输出No MCP servers configured yet.这与codex_apps报错并不矛盾因为codex_apps是内置连接器不一定出现在手动配置的 MCP 列表中。四、为什么删除auth.json后仍可能报错初步尝试通常包括codexlogoutcodex login statusrm-f$HOME/.codex/auth.jsonrm-f$HOME/.codex/oauth.jsoncodex login但删除文件后codex_apps仍可能继续返回HTTP 401 token_revoked原因可能包括实际使用的CODEX_HOME不是$HOME/.codex凭证存储在系统 keyring 中主认证与 Apps OAuth 是两套认证其他 Codex 进程仍持有旧 token另一台设备或 IDE 扩展触发了 token 轮换服务端已经撤销旧 refresh token工作区切换导致旧授权失效因此删除默认目录中的 JSON 文件不一定代表所有认证状态都已清除。五、创建隔离的干净认证环境为了排除旧缓存和系统 keyring可以创建一个全新的CODEX_HOME。codexlogout2/dev/null||trueunsetOPENAI_API_KEYunsetCODEX_ACCESS_TOKENunsetCODEX_API_KEYexportCODEX_CLEAN_HOME$HOME/.codex-clean-testexportCODEX_HOME$CODEX_CLEAN_HOMErm-rf$CODEX_HOMEinstall-d-m700$CODEX_HOMEprintf%s\n\cli_auth_credentials_store file\$CODEX_HOME/config.tomlchmod600$CODEX_HOME/config.tomlcodex login --device-auth设备码登录时打开终端显示的官方登录页面输入一次性设备码登录正确的 ChatGPT 账号选择正确的个人或团队工作区登录完成前不要在其他终端执行codex logout登录成功后会显示Successfully logged in六、为什么“刚登录能用”随后又提示 refresh token revoked可能出现以下现象设备码登录成功Codex 界面可以启动模型菜单可以切换真正发送模型请求时出现Your access token could not be refreshed because your refresh token was revoked.这两件事并不矛盾。Codex 登录凭证通常包括access_token refresh_token id_token刚登录后新的access_token可能暂时有效因此 Codex 可以启动界面读取配置显示模型列表执行部分本地操作当 access token 需要刷新时Codex 会使用refresh_token。如果 refresh token 已被撤销或轮换就会在这时暴露错误。因此codex login status只能说明本地存在登录信息不代表完整认证链路一定正常。必须通过真实模型请求验证。七、重新生成主认证首先关闭可能持有旧凭证的进程pkill-TERM-xcodex2/dev/null||truepkill-TERM-fcodex.*app-server2/dev/null||truesleep2pgrep-afcodex||true固定认证目录并清除环境变量exportCODEX_HOME$HOME/.codex-clean-testunsetOPENAI_API_KEYunsetCODEX_ACCESS_TOKENunsetCODEX_API_KEY备份旧认证mkdir-p$CODEX_HOME/auth-backupif[-f$CODEX_HOME/auth.json];thencp-a$CODEX_HOME/auth.json\$CODEX_HOME/auth-backup/auth.json.$(date%Y%m%d-%H%M%S).bakfi删除失效凭证rm-f$CODEX_HOME/auth.jsonrm-f$CODEX_HOME/oauth.json重新登录codex login --device-auth八、关闭异常的codex_apps如果主模型功能正常但codex_apps仍然持续报token_revoked可以临时关闭 Apps 集成。写入配置printf%s\n\cli_auth_credentials_store file\\[features]\apps false\$CODEX_HOME/config.tomlchmod600$CODEX_HOME/config.tomlcat$CODEX_HOME/config.toml正确内容cli_auth_credentials_store file [features] apps false关闭apps不会影响本地代码读取修改文件Shell 命令Git编译和测试/review普通模型调用Remote Control关闭后暂时不能使用ChatGPT Apps外部 Connectors依赖codex_apps的托管 MCP 工具九、安全检查认证文件检查登录状态codex login statusls-l$CODEX_HOME/auth.json正常应看到Logged in using ChatGPT并且auth.json权限应类似-rw-------可以使用下面的 Python 脚本只检查 token 字段是否存在不显示真实内容python3 -PY import json import os codex_home os.environ.get( CODEX_HOME, os.path.expanduser(~/.codex), ) path os.path.join(codex_home, auth.json) with open(path, r, encodingutf-8) as f: auth json.load(f) tokens auth.get(tokens) or {} print(auth_file:, path) print(auth_mode:, auth.get(auth_mode)) print(has_access_token:, bool(tokens.get(access_token))) print(has_refresh_token:, bool(tokens.get(refresh_token))) print(has_id_token:, bool(tokens.get(id_token))) print(last_refresh_exists:, bool(auth.get(last_refresh))) PY正常结果auth_mode: chatgpt has_access_token: True has_refresh_token: True has_id_token: True last_refresh_exists: True不要公开执行或粘贴cat$CODEX_HOME/auth.json也不要公开access tokenrefresh tokenid tokenCookieAuthorization header完整auth.json十、使用真实模型请求验证认证不要只依赖codex login status应当执行真实请求env-uOPENAI_API_KEY\-uCODEX_ACCESS_TOKEN\-uCODEX_API_KEY\CODEX_HOME$CODEX_HOME\codexexec\--skip-git-repo-check\--ephemeral\Reply with exactly OK and nothing else.可能出现三类结果。10.1 返回OK说明以下链路正常auth.json → access token → Codex 服务 → 模型响应10.2 返回refresh token was revoked说明主认证仍然失效需要重新停止所有 Codex 进程并执行设备码登录。10.3 返回Youve hit your usage limit说明认证已经成功只是当前模型额度耗尽。额度错误不是认证错误不需要继续反复退出登录。十一、默认模型额度耗尽后的处理默认模型可能返回Youve hit your usage limit. Try again at RESET_TIME.这说明账号认证正常 当前模型额度耗尽可以切换到仍有可用额度的 Spark 模型env-uOPENAI_API_KEY\-uCODEX_ACCESS_TOKEN\-uCODEX_API_KEY\CODEX_HOME$CODEX_HOME\codexexec\-mgpt-5.3-codex-spark\--skip-git-repo-check\--ephemeral\Reply with exactly OK and nothing else.返回OK即表示 Spark 可用。交互式启动codex-mgpt-5.3-codex-spark设为默认模型model gpt-5.3-codex-spark完整配置示例model gpt-5.3-codex-spark cli_auth_credentials_store file [features] apps false十二、不要移动整个$HOME/.codex曾经为了隔离旧状态移动了整个默认目录mv$HOME/.codex$HOME/.codex-broken-backup随后执行codex可能出现No such file or directory原因是 standalone 安装方式下$HOME/.codex不只是认证目录还可能包含$HOME/.codex/packages/standalone/current/codex$HOME/.local/bin/codex可能依赖这个实际程序路径。所以移动整个$HOME/.codex可能同时移走Codex standalone 程序app-serverRemote Control 所需组件版本元数据安装器管理文件恢复方法mv$HOME/.codex-broken-backup$HOME/.codexhash-r以后需要重置认证时只处理$CODEX_HOME/auth.json $CODEX_HOME/oauth.json不要直接删除或移动整个$HOME/.codex。十三、Remote Control 找不到 standalone 安装在使用隔离目录时exportCODEX_HOME$HOME/.codex-clean-test执行codex remote-control start可能报错managed standalone Codex install not found at $CODEX_HOME/packages/standalone/current/codex原因是干净目录中只有auth.json config.toml但 Remote Control 要求当前CODEX_HOME中同时存在packages/standalone/current/codex普通 Codex 命令可以通过 PATH 中的入口运行但 Remote Control daemon 要求使用安装器管理的固定 standalone 路径。十四、将有效认证迁移回正式目录首先确认正式目录中存在 standaloneexportCODEX_HOME$HOME/.codexls-l$CODEX_HOME/packages/standalone/current/codex停止相关进程pkill-TERM-xcodex2/dev/null||truepkill-TERM-fcodex.*app-server2/dev/null||truesleep2备份正式目录中的旧认证mkdir-p$HOME/.codex/auth-backupif[-f$HOME/.codex/auth.json];thenmv$HOME/.codex/auth.json\$HOME/.codex/auth-backup/auth.json.old.$(date%Y%m%d-%H%M%S)fiif[-f$HOME/.codex/config.toml];thencp-a$HOME/.codex/config.toml\$HOME/.codex/auth-backup/config.toml.old.$(date%Y%m%d-%H%M%S)fi复制已验证成功的认证和配置install-m600\$HOME/.codex-clean-test/auth.json\$HOME/.codex/auth.jsoninstall-m600\$HOME/.codex-clean-test/config.toml\$HOME/.codex/config.toml统一使用正式目录exportCODEX_HOME$HOME/.codexunsetOPENAI_API_KEYunsetCODEX_ACCESS_TOKENunsetCODEX_API_KEYhash-r验证echo$CODEX_HOMEcodex login statusls-l$CODEX_HOME/packages/standalone/current/codex十五、迁移后验证 Sparkenv-uOPENAI_API_KEY\-uCODEX_ACCESS_TOKEN\-uCODEX_API_KEY\CODEX_HOME$HOME/.codex\codexexec\-mgpt-5.3-codex-spark\--skip-git-repo-check\--ephemeral\Reply with exactly OK and nothing else.返回OK说明有效认证已经成功迁移到正式CODEX_HOME。十六、启动 Remote Control统一目录后执行exportCODEX_HOME$HOME/.codexcodex remote-control stop2/dev/null||truecodex remote-control start codex remote-control pair启动成功时会出现类似Starting app-server daemon with remote control enabled... This machine is available for remote control as SERVER_HOSTNAME. Daemon used app-server: path: CODEX_HOME/packages/standalone/current/codex version: CODEX_VERSION Pairing code: PAIRING_CODE不要公开真实配对码。如果配对码曾被发到聊天、论坛、截图或日志中应重新生成codex remote-control pair只在自己的受信任设备中输入新配对码。十七、永久固定CODEX_HOME将正式目录写入 Shell 配置grep-qxFexport CODEX_HOME$HOME/.codex$HOME/.bashrc||echoexport CODEX_HOME$HOME/.codex$HOME/.bashrcsource$HOME/.bashrc验证echo$CODEX_HOME应输出用户主目录/.codex检查最终配置cat$CODEX_HOME/config.toml推荐配置model gpt-5.3-codex-spark cli_auth_credentials_store file [features] apps false十八、可直接复用的标准恢复流程18.1 固定正式目录exportCODEX_HOME$HOME/.codex18.2 排除环境变量干扰unsetOPENAI_API_KEYunsetCODEX_ACCESS_TOKENunsetCODEX_API_KEY18.3 停止旧进程pkill-TERM-xcodex2/dev/null||truepkill-TERM-fcodex.*app-server2/dev/null||truesleep218.4 备份认证mkdir-p$CODEX_HOME/auth-backupif[-f$CODEX_HOME/auth.json];thencp-a$CODEX_HOME/auth.json\$CODEX_HOME/auth-backup/auth.json.$(date%Y%m%d-%H%M%S).bakfi18.5 删除失效认证rm-f$CODEX_HOME/auth.jsonrm-f$CODEX_HOME/oauth.json18.6 写入最小配置printf%s\n\model gpt-5.3-codex-spark\cli_auth_credentials_store file\\[features]\apps false\$CODEX_HOME/config.tomlchmod600$CODEX_HOME/config.toml18.7 重新登录codex login --device-auth18.8 验证登录结构codex login statusls-l$CODEX_HOME/auth.json18.9 进行真实模型测试env-uOPENAI_API_KEY\-uCODEX_ACCESS_TOKEN\-uCODEX_API_KEY\CODEX_HOME$CODEX_HOME\codexexec\-mgpt-5.3-codex-spark\--skip-git-repo-check\--ephemeral\Reply with exactly OK and nothing else.18.10 启动 Remote Controlcodex remote-control stop2/dev/null||truecodex remote-control start codex remote-control pair十九、错误信息快速判断表codex_apps token_revokedMCP client for codex_apps failed HTTP 401 token_revoked含义Apps/Connectors OAuth 失效临时处理[features] apps falserefresh token was revokedYour access token could not be refreshed because your refresh token was revoked.含义Codex 主认证失效处理停止所有 Codex 进程 删除 auth.json 重新执行设备码登录 使用 codexexec真实验证Youve hit your usage limit含义认证成功但当前模型额度耗尽处理codex-mgpt-5.3-codex-spark不要因此反复退出登录。No such file or directory如果 Codex 命令入口突然失效并且此前移动过$HOME/.codexstandalone 安装目录被移动恢复mv$HOME/.codex-broken-backup$HOME/.codexhash-rmanaged standalone Codex install not found含义当前 CODEX_HOME 中没有 standalone 安装处理统一使用包含 packages/standalone 的正式 CODEX_HOME 或在当前 CODEX_HOME 下重新运行 Codex installerRemote control is not enabled for this team含义当前团队工作区可能未开放 Remote Control检查手机与服务器是否使用同一账号是否选择了同一个工作区个人工作区是否可用团队管理员是否启用了相关权限二十、公开分享时必须删除的信息发布日志或教程前必须删除或替换真实主机名 公网 IP SSH 地址 用户名 会话 ID codex resume ID 设备登录码 Remote Control 配对码 access token refresh token id token Cookie Authorization header 完整 auth.json 团队名称 个人邮箱 精确额度恢复时间推荐替换格式SERVER_HOSTNAME SERVER_IP USERNAME SESSION_ID DEVICE_CODE PAIRING_CODE RESET_TIME WORKSPACE_NAME可以公开错误类型 通用目录结构 脱敏后的命令 软件版本 配置字段 不包含 token 的布尔检查结果二十一、核心经验codex_apps错误与 Codex 主模型认证不是同一层问题。codex login status不能替代真实模型请求验证。usage limit表示认证成功不是 token 失效。standalone 安装下不要移动整个$HOME/.codex。Remote Control 要求当前CODEX_HOME中存在 standalone 程序。配置、认证和 Remote Control 最好统一使用同一个正式CODEX_HOME。出现认证问题时只重置认证文件不要删除整个安装目录。所有设备码、配对码和 token 都不应出现在公开日志中。