环境与登录
急救手册

对症快查 + 问题地图

对症快查:30 秒定位你的问题

问题地图:所有环境问题只有四类根源

Claude Code 与 Codex 的"环境问题"看似五花八门,拆开只有四类根源。认清根源,后面所有章节都是在这张地图上定位、修复。

两个工具,同一套心智模型

好消息:两个工具的环境体系高度同构,学一遍方法论,两边通用。

完整对照表见第 13 章。本页所有结论均核对官方文档 2026-07 版,来源见各节脚注。

五层诊断：先确认来源，再做最小修改

从错误证据选择层级，不必机械执行全部步骤。多个安装路径、代理或凭据变量并不自动代表异常；先确认当前入口实际使用了什么。以下检查不读取密钥文件、不打印环境变量值。

# macOS / Linux / WSL：只读检查，输出环境变量名，不输出值
for tool in codex claude; do
  if command -v "$tool" >/dev/null 2>&1; then
    command -v "$tool"
    "$tool" --version
  fi
done
env | cut -d= -f1 | sort | grep -iE 'anthropic|claude|codex|openai|proxy|ca_bundle|node_extra_ca' || true
# 只列可能的配置位置，不读取内容
for file in "$HOME/.codex/config.toml" "$HOME/.claude/settings.json"             ".codex/config.toml" ".claude/settings.json" ".claude/settings.local.json"; do
  [ ! -f "$file" ] || printf '%s\n' "$file"
done

PowerShell 可用 Get-Command codex,claude -All 查入口；仅列变量名：Get-ChildItem Env: | Where-Object Name -match 'ANTHROPIC|CLAUDE|CODEX|OPENAI|PROXY' | Select-Object -ExpandProperty Name。不要把不带最后 Select-Object 的完整值输出发到工单。

依据：Codex 配置层 · Claude 设置排错

Claude Code · 认证与凭据入口

核对至 2026-10-20。认证包括 claude.ai 订阅/团队、Claude Console（有条件支持无 Key 登录）、API 凭据、云提供商、企业网关和 profile/工作负载身份。凭据选择取决于运行模式和组织要求，不能把旧版固定优先级视为全部场景通用。

CLI/包装 CLI 的环境变量和 apiKeyHelper 不能直接套用到桌面或云端。macOS Keychain、受限文件回退、Linux/Windows 存储按当前认证文档核实。

配置与认证完整说明 →

依据：官方认证

Claude Code · 设置文件与字段入口

设置文件优先级为托管 → CLI --settings → 项目 local → 共享项目 → 用户；环境变量按字段决定优先级，数组还有特例。settings.json 是严格 JSON，不能写注释或尾逗号。

本站设置与登录指南 → · 官方全部设置（作用域、默认和示例）→

auto/bypassPermissions 等模式不能从项目/local 文件启用；多数设置可热重载，但模型、思考档等需按对应入口切换。

依据：设置文件

Claude Code · 分层排错入口

先用 claude --version、claude --help、claude auth status 与只读 claude doctor 查版本和配置错误；会话内 /status 查 Setting sources、/permissions 查规则来源。不要把修改 base URL 误当作切换计费或凭据。

常见问题 → · 本机核对 →

Codex · 认证与凭据入口

核对至 2026-10-20。官方个人认证主要有 ChatGPT 登录与 API Key；设备码是登录流程，不能当成第三种独立计费身份。自定义网关可有环境 Bearer、自定义头、命令 Token，ChatGPT 经网关则需要双凭据；Bedrock 和企业自动化另有路径。

先用 codex login status 确认官方登录状态，再检查实际选择的 provider。模型登录凭据、MCP OAuth、网关凭据分别管理；不存在一条脱离提供商与运行模式的万能优先级表。

完整认证矩阵、存储与互斥说明 →

依据：官方认证

Codex · config.toml 配置专题

配置详解已并入 Codex 指南，按 7 个专题组织。内容覆盖 306 条公开配置路径、103 个 Schema 顶层键和 996 条结构路径，重点解释 provider、认证、URL、必需项、互斥与迁移。

进入 config.toml 全面解析 →

关键纠正：项目层先于独立 profile；项目层不能改提供商；≥0.134.0 profile 改独立文件；wire_api 只支持 responses；name 只是显示名。

依据：配置基础 · 高级配置

Codex · 分层排错入口

先记录版本、启动入口、错误来源和所选 provider。401/403 查凭据及服务权限，404/405 查路由，400/422 查模型与协议，流中断查 SSE/WebSocket 和代理。不要先删 auth.json 或开启全访问。

症状排错表 → · 本机命令核对 →

剧本 A · 共用电脑 / 接手"别人配置过"的电脑

最高频的翻车现场:你是 Claude 会员,坐到一台别人用过的电脑前,一顿操作后各种报错。根因几乎总是同一个:上一位使用者的凭证与环境变量还活着,而它们的优先级比你的登录高。

上机三查(动手配置之前先做)

1. 查环境变量与 rc 残留:跑第 01 章体检脚本,重点看 L2 输出——别人 rc 文件里的 export ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL(中转站配置)/ OPENAI_API_KEY 就是定时炸弹。
2. 查凭证归属:claude 进会话 /status 看登录的是谁的账号;codex login status 同理。是别人的就先 /logout / codex logout。
3. 查全局配置污染:~/.claude/CLAUDE.md、~/.claude/settings.json、~/.codex/config.toml、~/.codex/AGENTS.md 里是不是别人的偏好与指令——这些会直接影响你的每次对话行为。

按共用程度选方案

同一系统账号跑多套配置(隔离方案)

# ~/.zshrc —— 每人/每个账号一个独立配置目录 + 专属命令
# Claude Code:CLAUDE_CONFIG_DIR 决定"老家"在哪
alias claude-me='CLAUDE_CONFIG_DIR="$HOME/.claude-me" claude'
alias claude-work='CLAUDE_CONFIG_DIR="$HOME/.claude-work" claude'
# Codex:CODEX_HOME 同理
alias codex-me='CODEX_HOME="$HOME/.codex-me" codex'
alias codex-work='CODEX_HOME="$HOME/.codex-work" codex'

• 每个目录首次使用时各自走一遍登录,凭证、历史、配置完全隔离,从此不用反复登出登入;
• 防串门技巧:不同账号会话里用 /color 换界面主题色,一眼看出"我现在是谁"(社区 madewithlove 方案);
• 注意 Claude Code 还有一个全局状态文件 ~/.claude.json(MCP 等),设了 CLAUDE_CONFIG_DIR 后随目录走——别再手动去动默认位置的那份。

参考:Running multiple Claude accounts without logging out(madewithlove) · Two Claude accounts on one Windows PC(Josh Grossman) · codex-multi-auth(社区工具)

剧本 B · 换电脑 / 多机漫游

核心原则一句话:配置随身走,凭证每机新登,历史留在原地。想清楚"什么带走、什么不带",换机就是十分钟的事。

带什么、不带什么(双工具对照)

新机十分钟标准流程

# 1. 安装(官方 native 渠道,别混用 npm)
curl -fsSL https://claude.ai/install.sh | bash        # Claude Code
npm install -g @openai/codex                          # Codex(或 brew install codex)

# 2. 恢复配置(dotfiles 方案)
git clone git@github.com:你/dotfiles.git ~/dotfiles
ln -s ~/dotfiles/claude ~/.claude                     # 或 export CLAUDE_CONFIG_DIR=~/dotfiles/claude
ln -s ~/dotfiles/codex ~/.codex                       # 或 export CODEX_HOME=~/dotfiles/codex

# 3. 各登录一次(凭证绝不拷贝)
claude          # 浏览器 OAuth → /status 验证账号与 Login method
codex login     # 浏览器 OAuth → codex login status 验证

# 4. 体检收尾
claude doctor && bash ai-env-check.sh

参考:官方 ~/.claude 目录详解 · anthropics/claude-code#36693(多机同步討論)

剧本 C · SSH / 容器 / 无头机 / CI

没有浏览器的环境,登录是另一套打法。两个工具的官方推荐路径不同,别互相套用。

Claude Code:三条路径

1. SSH/WSL2/容器交互使用:正常跑 claude,把终端里的 OAuth URL 复制到本地浏览器完成登录,浏览器给出的 code 粘回终端(粘贴失灵就用 claude auth login 从 stdin 读)。
2. CI / 脚本(订阅额度):在本地跑 claude setup-token 生成一年期 OAuth token,存进 CI Secret,运行环境设 CLAUDE_CODE_OAUTH_TOKEN。注意 --bare 模式不读它,bare 场景改用 ANTHROPIC_API_KEY 或 apiKeyHelper。
3. CI(API 计费):直接 ANTHROPIC_API_KEY 环境变量——最简单,但走按量计费。

Codex:官方三方案按优先级

1. 设备码(首选):codex login --device-auth,本地任意浏览器输一次性码。工作区可能需要管理员先启用设备码权限。
2. 拷贝 auth.json(官方兜底):有浏览器的机器登录后把 ~/.codex/auth.json 安全复制到目标机(scp / docker cp)。若本机凭证在钥匙串而非文件,先把 cli_auth_credentials_store 设为 file 重登一次。
3. SSH 端口转发:ssh -L 1455:localhost:1455 user@remote 后在远端 codex login,本地浏览器走标准流程。

Codex CI 长期认证(官方 auth.json 续期循环)

ChatGPT 订阅额度跑 CI 的官方姿势——利用 Codex 运行时自动刷新 token 并回写 auth.json 的机制:

1. 可信机器上 codex login(file 存储),把生成的 auth.json 存入 CI 的 Secret 管理;
2. 每次任务:恢复 auth.json → 跑 Codex(token 约 8 天不刷会失效,运行中自动续期)→ 回写刷新后的 auth.json 到 Secret;
3. 红线:不要多个并发任务共享同一份 auth.json;不要每次都用最初的旧文件覆盖新文件;刷新链断了就回可信机器重新登录播种。自托管 runner 直接给个持久 CODEX_HOME 更省事。

公司网络(代理 / 私有 CA)速查

来源:官方 Authentication(setup-token) · 官方 Codex CI/CD auth(2026-07 版)

案例复盘:从症状到根因

四个高频真实场景,把五层诊断法从头到尾走一遍。看懂这四个,大多数"玄学问题"你都能自己破案——注意每个案例里报错文本和真正根因隔了多远。

案例一 · "我是 Max 会员,却提示组织已停用"

案例二 · "VS Code 扩展一直 Invalid API key,终端却好好的"

案例三 · "一觉醒来,所有并行会话集体要求重新登录"

案例四 · "Codex 在 CI 里稳定跑了一周,突然全线 401"

案例依据:官方 troubleshoot-install / authentication 文档、anthropics/claude-code#12204、Codex CI/CD auth 官方指南(2026-07 核对);机器与人物细节做了场景化改写,排查路径与根因均为真实机制。

可恢复的排查与重置

先保存错误、版本、实际生效配置和脱敏日志。只在证据指向凭据问题时重新登录，只在确认变量来源与用途后调整环境。不要把清空全部配置目录当作通用修复；原流程的选择性备份不能恢复被删除的全部会话、技能和状态。

需要隔离配置时，先确认实际配置目录（包括自定义目录），完整复制到有时间戳的独立位置并检查可读取；保留原目录，再一次只禁用或调整一个已确认有问题的文件。验证失败就恢复该项。重置后仍失败并不能证明问题一定在服务端。

双工具概念对照 + 资源索引

一张表打通两个工具

资源索引(按可信度排序)