最近身边不少同事都在同时折腾两件事装 Claude Code、装 Codex。原因也直白——写代码这件事正在从“编辑器里的补全”转向“终端里的 Agent 直接接管”这两套官方命令行工具是目前走得最前的两个代表。但大多数人卡的位置几乎一模一样官方登录通了却碰上账号可用地区的校验提示默认模型配额不够用想接 DeepSeek 这类第三方模型又搞不清 ANTHROPIC_BASE_URL 和 config.toml 里的 model_provider 到底怎么填配置理顺之后CC Switch 这类多配置切换工具还会抛来一串“本地转发通道失败”的错误看着跟天书一样。这篇文章把我最近几周的实测路径完整写下来从官方安装、登录验证、VSCode 集成到接入第三方模型再到 CC Switch 的坑怎么排最后补上 Skills、超长上下文和团队配置这些进阶用法。适合两类读者一类是刚下载 CLI 还没跑通第一句对话的新手另一类是想把官方工具和第三方模型服务统一管理起来的老手。1. 先搞清楚两套 CLI 的脾气Claude Code 与 Codex 的定位差距1.1 一句话描述这两个工具Claude Code 是 Anthropic 官方的终端编码 Agent核心玩法是在终端里用自然语言下指令它自己读代码、改文件、跑命令你只需要盯着 diff 和审批请求。Codex 是 OpenAI 官方的同类工具思路几乎一样默认接的是 GPT-5.x 系列模型订阅了 ChatGPT Plus 及以上套餐就能用也支持带自己的 OpenAI API Key。这两个工具同时装在同一台机器上完全不冲突配置文件、登录态、CLI 命令都是独立的。麻烦的是它们对“第三方模型”的接入方式差得比较远网上很多教程把两者混着讲照着抄就容易出现“在 Claude Code 里找 config.toml、在 Codex 里找 ANTHROPIC_BASE_URL”这类错位操作。所以第一步不是装工具而是把它们的配置入口记清楚。1.2 账号体系、计费模型和模型路线的差异我把两者最关键的差异整理成了表格后面所有排错都能回到这张表对比项Claude CodeCodex官方登录Claude.ai 订阅账号OAuth或 Anthropic API KeyChatGPT 账号OAuth或 OpenAI API Key默认模型路线Opus / Sonnet 系列GPT-5.x Codex 系列第三方兼容端点走 Anthropic 兼容协议靠环境变量注入走 OpenAI 兼容协议靠 config.toml 的 model_provider配置文件~/.claude/settings.json、项目 .claude/settings.json~/.codex/config.toml扩展机制Skills、Subagents、MCP、HooksMCP、Agents SDK、云端任务典型报错region 不可用提示auth token 不可用、model not supported这张表的核心信息是Claude Code 的第三方接入依赖的是“Anthropic 兼容端点”比如 DeepSeek 官方提供的 /anthropic 接口Codex 的第三方接入依赖的是“OpenAI 兼容端点 /chat/completions”。两者协议不同工具调用格式也不同所以不存在一个配置两边通用的说法。后面第三章会分别展开。还有一个容易被忽略的点这两套 CLI 的“官方账号登录”和“API Key 调用”在内部是两个体系报错样式完全不同。账号体系报的是登录态、配额、区域校验API Key 体系报的是 401、余额、模型不存在。你拿到一条报错先判断它来自哪一层再动手查比到处搜错误码高效得多。2. 官方安装与登录实践从 npm 到桌面版再到 VSCode 插件2.1 Claude Code 的官方安装路径Claude Code 最省心的安装方式是 npm 全局安装前提是机器上有 Node.js。我的建议是 Node 版本至少 18最好用 20 以上的 LTS旧版本的 Node 在解析一些新语法时会出奇怪的问题而且报错信息不会直接告诉你“你的 Node 太老”。node -v npm -v npm install -g anthropic-ai/claude-code claude --versionUbuntu 上最常见的坑是 npm 全局目录权限不足报一串 EACCES。如果你是用 nvm 装的 Node一般不会遇到如果是系统包管理器装的 Node出现权限报错时别急着加 sudo先执行npm config get prefix看看全局目录再决定是修目录权限还是换用 nvm。理由是sudo 装全局包会把 package 文件变成 root 所有之后任何用户级更新都容易碰壁长期看是给自己埋雷。Windows 上除了 npm 安装官方还提供桌面版应用也叫 Claude Code 桌面版。桌面版本质上是把 CLI 包了一层壳好处是登录流程、自动更新、配置管理都在图形界面里完成对不熟悉命令行的同事友好很多。我实测下来桌面版和 CLI 共用的还是同一套配置文件你在桌面版里切换的 model回到终端里跑 claude 一样生效。官方桌面版从官网下载就好尽量别用第三方转载的安装包安全性没法保证。Linux 桌面版目前在部分发行版上有Ubuntu 用户如果不想折腾桌面版直接用 CLI 反而更顺手。安装完成后执行claude login浏览器会跳出 OAuth 授权页登录你的 Claude.ai 账号即可如果你只有 API Key也可以不登录直接export ANTHROPIC_API_KEYsk-ant-你的key claude这里要提醒一句如果你打算以第三方模型为主就不要混着设官方 API Key 和 ANTHROPIC_BASE_URL。环境变量之间存在覆盖关系两个都设的时候CLI 会优先用 BASE_URL 指向的服务但部分子命令仍会尝试用官方 Key 做校验结果就是你看到“一会儿通一会儿不通”的诡异现象。我后面的做法是用第三方模型时专门开一个干净的终端把官方变量全部 unset 掉。2.2 区域校验提示跟“安装失败”是两回事很多人在安装后第一次登录时看到类似 “note: claude code might not be available in your country. check supported countries” 的提示第一反应是安装包有问题。其实安装包没问题这是客户端的账号区域校验官方会根据账号归属地、支付方式等因素判断你当前是否在支持范围内。这个问题在官方文档里有明确的 supported countries 列表先核对账号资料里的地区和账单地址是否真实一致。我的建议比较简单如果确认账号信息没问题可以找官方支持渠道确认如果确实不在支持范围就别去碰那些灰色手段——一是违反服务条款二是靠不住三是账号一旦被封损失远大于省下的那点功夫。更务实的路线是直接走“API Key 第三方模型”这条路也就是第三章讲的内容。这条路对官方 CLI 本身没有任何影响照样能把 Claude Code 用得像模像样。2.3 Codex 的安装、登录和 auth token 报错Codex CLI 一样是 npm 包npm install -g openai/codex codex --version首次运行codex或执行codex login会走 ChatGPT 账号的 OAuth 登录部分地区的账号还需要短信验证码。热词里那个“codex手机号验证”指的就是这一步。正常情况下按官方流程绑定手机号、收验证码就能过如果你绑定的号码收不到码先检查账号本身是否处于正常状态别重复发送把验证码频控触发得更高。登录完成后Codex 会把凭证写到~/.codex/auth.json。于是有个很典型的报错codex auth token is unavailable。这个报错我见过三种触发场景本质都是“CLI 拿不到有效凭证”根本没有登录过auth.json 不存在在 SSH、CI、无头服务器这类非交互环境里OAuth token 流程走不了你同时设置了 OPENAI_API_KEY 环境变量但部分子命令仍坚持去读 auth.json。处理方法交互终端里重新codex loginCI 环境改用 API Key即设置 OPENAI_API_KEY 并把 config.toml 里的 provider 指到 openai如果确认是 auth.json 损坏备份后删掉再重新登录。注意 auth.json 里是明文 token千万别提交进 git。Codex 也有官方桌面应用和 IDE 扩展登录方式与 CLI 一致桌面版适合不想碰命令行的场景。2.4 VSCode 里同时挂两个助手Claude Code 在 VSCode 里有官方扩展安装后用同一个账号授权就能在侧边栏直接对话它本质上是调用你已经装好的 CLI所以之前说的环境变量配置同样生效。Codex 也有官方 VSCode 扩展安装后在面板里登录 ChatGPT 账号即可。同一个工作区同时启用两个扩展我不反对但有两个实操提醒。其一它们各自维护上下文你不要指望 Codex 面板里聊到一半的内容能无缝转到 Claude Code 里继续跨工具接续上下文目前只能靠你手动把关键结论粘贴过去。其二两者默认的权限控制都比较保守会逐个请求批准文件读写和命令执行如果你赶时间很容易想开全自动模式但生产仓库我强烈建议保持默认审批全自动模式在 CI 或沙箱环境里玩一玩可以本地仓库一旦误删文件后悔都来不及。3. 接入第三方模型把 DeepSeek 这类服务变成主力后端3.1 为什么要把模型换成第三方这个问题几乎每个折腾的人都问过。我总结下来就三个动机成本、区域可用性、模型偏好。官方订阅账号有配额限制重度使用很快就到天花板API 按量计费对高频短任务反而更划算。区域问题前面说过了官方账号不可用的时候第三方模型服务是另一条可行的路径——只要你使用的是该服务商公开提供的 API 和端点并且遵守它的使用条款。模型偏好就纯粹是个人口味了有些场景下第三方模型的推理表现确实更符合一些开发者的习惯。理解第三方接入的关键在于CLI 本身不会变变的只是“base_url 指向谁”和“认证 token 用谁的”。Claude Code 和 Codex 都内置了这种可配置性这也是它们能接第三方模型的原因。3.2 Claude Code 接 DeepSeek首选 Anthropic 兼容端点DeepSeek 官方提供了一个 Anthropic 兼容端点地址是 https://api.deepseek.com/anthropic模型名用 deepseek-chat 或 deepseek-reasoner。这等于官方替你做掉了协议翻译层Claude Code 连中间件都不用装三个环境变量搞定export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKENsk-你的DeepSeekKey export ANTHROPIC_MODELdeepseek-chat # 后台小任务生成标题、总结、判断是否需要工具可以指定更快更省的模型 export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat claude为什么用 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY因为这是第三方兼容端点的通用约定AUTH_TOKEN 被当作 Bearer token 原样交给服务端鉴权而 API_KEY 触发的是一些官方专用的校验逻辑用在第三方服务上容易出莫名奇妙的问题。DeepSeek 的 /anthropic 端点自己也建议用 AUTH_TOKEN照着做就行。设置完执行claude进去后敲/status看一眼 Current Model 和 API endpoint确认指向的是 DeepSeek 而不是官方。然后随便让它改一个小函数看返回速度、工具调用是否正常。我实测 DeepSeek 这个端点的工具调用是能跑通的但如果你遇到工具调用不稳定的情况第一反应应该是去查 DeepSeek 官方文档里关于 Anthropic 兼容端点的限制说明而不是怀疑 CLI 坏了。如果某家模型服务商只有 OpenAI 兼容端点、没有 Anthropic 兼容端点那 Claude Code 直接连就绕不过协议差异了。这种情况通常需要中间层做协议转换社区里有不少路由类工具。我的个人意见是能不用中间层就不用每多一层排错就多一层黑盒尽量选那些官方自带了 Anthropic 兼容端点的服务商。3.3 Codex 接 DeepSeekconfig.toml 里的 model_providerCodex 对第三方模型的支持是原生的核心配置在~/.codex/config.toml。DeepSeek 是 OpenAI 兼容协议所以 wire_api 要写 “chat”而不是 OpenAI 官方最新的 “responses”。一个可以直接用的最小配置# ~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat然后导出 key 并启动export DEEPSEEK_API_KEYsk-你的DeepSeekKey codex这里解释一下每个字段的用意。model 决定请求体里带上什么模型名必须是 provider 真实支持的model_provider 指向下方定义的 provider 块base_url 只填服务商的主域名或明确给的 API 域名别画蛇添足加 /v1否则请求路径可能变成 /v1/v1/chat/completions 这种双路径env_key 告诉 CLI 从哪个环境变量读取密钥让密钥不必硬编码进配置文件wire_api 则是协议开关DeepSeek 这类只实现了 chat 的服务必须写 “chat”。如果你同时保留官方的 OpenAI 配置建议用 profile 做隔离model gpt-5.1-codex model_provider openai [profiles.deepseek] model deepseek-chat model_provider deepseek [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 wire_api responses env_key OPENAI_API_KEY [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com wire_api chat env_key DEEPSEEK_API_KEY之后想用哪套就哪套交互式codex默认走官方配置需要切换到第三方时启动命令加--profile deepseek即可比反复改配置文件省事得多。3.4 模型名和协议不匹配的那些经典报错用第三方模型时两类报错出现频率最高。第一类跟你设置的模型名有关。Codex 默认会带上官方模型名比如请求体里出现 gpt-5.x 系列第三方服务端根本认不出来于是上游返回类似the gpt-5.6-sol model is not supported when using codex with a...的错误。这个报错不是 Codex 的 bug是上游在告诉你“你别拿 OpenAI 的模型名来问我。”解法就是改 model 字段把它换成 deepseek-chat 或 deepseek-reasoner 这类服务商真实支持的模型名。第二类跟协议有关。OpenAI 的 responses API 和 chat completions 对工具调用的结构化方式完全不同第三方如果没有实现 /responses 端点而你还把 wire_api 设成 “responses”那请求一到就失败。这类错误的特征是会出现在第一次工具调用前后而不是第一句对话。把 wire_api 改成 “chat” 之后请求会改走 /chat/completions绝大多数 OpenAI 兼容服务商都能正常响应。4. 用 CC Switch 统一管理多套配置本地转发报错的定位过程4.1 CC Switch 解决了什么问题当你同时有官方账号、DeepSeek、其他模型服务商好几套配置时每换一次都要手动改环境变量或编辑配置文件迟早出错。CC Switch 这类图形化切换工具解决的就是这个把多套“供应商配置”做成可视化的 profile一键切换它还会在本地起一个转发通道把多个后端的请求统一收口让那些只认固定 base_url 的工具也能动态选择后端。需要说明的是CC Switch 不改变任何协议规则它只是配置管理器和转发器。你直连时连不通的切到 CC Switch 一样连不通CC Switch 只是让你切换方便并不会魔法般地修复 wire_api 或模型名的问题。很多报错其实在直连时同样存在只是被 CC Switch 的一层转发包装成了更吓人的错误信息。4.2 复现一次“本地转发通道处理 codex 端点失败”的完整排查链路先说那个高频报错原文大意是cc switch 的本地转发通道在处理 codex 的 /responses 端点时连接失败。热词里那条 cc switch 处理 codex /responses 报错说的就是它。我看到这条信息的第一反应不是查网络而是先把它拆成两个问题谁在访问 /responses以及本地转发把请求转给谁、对方认不认 /responses我的排查链路是这样的你可以照着复现第一步先确认触发场景。这个报错几乎只在 Codex 配置下出现Claude Code 配置走的是另一套路径。如果你是在 CC Switch 里选了某个 Codex profile 后启动codex第一条请求就报这个说明请求已经到达 CC Switch 的本地转发通道问题出在转发通道到上游的环节。第二步打开 CC Switch 的日志和 codex 的详细输出。Codex 侧可以开 verbose 模式CC Switch 侧看日志面板。重点看转发通道实际请求的上游 URL 和 HTTP 状态。我遇到过的情况是上游返回 404/not implemented因为转发通道把请求按 /responses 路径转发过去而上游根本不提供这个端点。第三步检查 wire_api。Codex 默认走 responses 协议所以请求路径是 /responses。DeepSeek 等第三方大多只实现了 /chat/completions没有 /responses。你需要让 Codex 走 chat 协议要么在 config.toml 里把 provider 的 wire_api 改成 “chat”要么在 CC Switch 的 provider 配置里选对协议类型。改完之后转发通道发出的路径会变成 /chat/completions问题通常当场消失。第四步再检查模型名。协议对了之后如果请求体里还是 Codex 默认的官方模型名上游会继续报 model not supported。把 model 强制设成 deepseek-chat两边就对齐了。第五步查偶发因素。端口被占用、base_url 配置里带了多余的路径前缀、上游限流返回 429这些都会让转发通道报连接失败。日志里 HTTP 状态码 404 和 429 的修法完全不同一定要先看状态码再动手。这套链路走完之后可以下一个结论这个报错九成以上是“协议类型 模型名”两者之一没对齐跟网络没有关系。还有一成是 base_url 路径写错属于手滑。4.3 一个容易被忽略的配置归属问题CC Switch 在切换供应商时是通过改写配置文件来实现的。Claude Code 这边它改的是 settings.json 里的环境变量块Codex 这边它会调整 config.toml。问题来了如果你在 shell 的 .bashrc 里显式 export 了 ANTHROPIC_BASE_URL 或 OPENAI_BASE_URL 这类变量这些外部环境变量会跟 CC Switch 写进配置的变量打架结果就是“我在 CC Switch 里明明切了 DeepSeek终端里跑起来还是官方”。我个人踩过这个坑之后定的规矩是同一个工具的配置入口只用一个。要么全部靠 CC Switch 管理要么全部写在 shell 配置里不要两处都写。如果一定要混用每次切换后开一个新终端并且先用env | grep -i anthropic检查残留变量确认没有旧变量盖掉新配置。5. 把官方能力用透Skills、超长上下文与团队配置5.1 手动安装 GitHub 上的 SkillsClaude Code 的 Skills 本质上就是“文件夹 一份 SKILL.md”。官方生态里有大量开源 skill 躺在 GitHub 上手动安装一点都不复杂。以用户级安装为例mkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/某用户/某skill仓库.git my-skill # 确认结构 ls ~/.claude/skills/my-skill/SKILL.md如果是项目级使用就放到仓库里的.claude/skills/skill-name/SKILL.md提交到 git 后整个团队都能共享。SKILL.md 的骨架大致是--- name: my-skill description: 在改某类文件、处理某类任务时使用给模型判断触发时机 --- # 执行步骤 1. 先读取相关文件 2. 按模板生成内容 3. 运行校验命令 # 注意事项 - 关键禁忌写在这里最容易被忽略的是 frontmatter 里的 description。它决定了模型会不会自动调用这个 skill写作重点是“在什么场景下、遇到什么任务时使用”而不是“这个 skill 多厉害”。安装完以后重启 claude用/skills能看到列表就算成功。Codex 侧目前没有和 Claude Skills 完全对等的目录式机制它的扩展更多走 MCP 和 Agents SDK所以这条主要针对 Claude Code。5.2 1M 上下文并不是默认开启的Claude Code 的超长上下文功能也就是热词里那个“claude code 1m上下文”是个很有吸引力的卖点。但要注意两点不是所有模型都支持 1M 上下文支持也需要在配置里显式开启。通常的做法是参考官方文档在 settings.json 里打开对应 experimental 项或者直接在/config菜单里找 1M Context 的开关。具体字段名在不同版本里有差异以你手上版本的提示为准我不建议照抄网上的旧配置很容易失效。1M 上下文能解决的是“整仓分析”这类场景——把整个代码库喂进去让它跨目录找关联、做大规模重构。但我不建议把日常小改动也丢进超长上下文里因为长上下文的推理时间、费用、响应首字时间都会明显上升很多小任务用默认窗口反而更快。另外上下文再长也有输出截断的风险超大上下文场景下更要习惯让它分步输出而不是指望一次把所有事情干完。5.3 一份可以提交到仓库的团队配置样例Claude Code 和 Codex 都支持把配置放进仓库这对团队统一行为很有用。Claude Code 侧建议在项目根目录放.claude/settings.json用 permissions 控制允许/拒绝的操作用 hooks 在特定命令执行前做拦截。一个不那么激进、适合起步的示例{ permissions: { allow: [ Read(workspace), Edit(workspace), Bash(git status), Bash(git diff), Bash(npm run lint) ], deny: [ Bash(rm -rf *), Bash(git push --force) ] }, hooks: { PreToolUse: [ { matcher: Bash(git push*), hooks: [ { type: command, command: echo push 操作已记录 /tmp/claude_hook.log } ] } ] } }这套配置的意思是Agent 读写仓库和跑常用命令不需要逐个询问但危险命令直接拒绝。注意别把密钥写进这种会被提交的文件环境变量和 key 一律走本地的 settings.local.json 或 shell 环境。Codex 侧把~/.codex/config.toml纳入 dotfiles 管理即可但前面说过~/.codex/auth.json属于凭证文件无论如何都不要提交。一个简单的 gitignore 规则可以避免手滑echo auth.json ~/.codex/.gitignore6. 高频报错速查表与我的实操建议6.1 一张表解决八成求助帖把这几周收集到的、群里同事问过的高频报错汇总成一张速查表每次看到同类问题直接对照报错/现象真实原因处理建议note: claude code might not be available in your country账号地区/支付校验不通过核对官方支持列表不碰灰色手段改用 API Key 或第三方模型codex auth token is unavailable未登录或凭证缓存失效交互环境重新 codex loginCI 用 OPENAI_API_KEY本地转发通道处理 codex /responses 失败wire_api 仍是 responses上游只支持 chat把 provider 的 wire_api 改成 chatthe gpt-5.6-sol model is not supported上游不认识官方模型名将 model 改为 deepseek-chat 等上游支持的模型401 unauthorized / invalid api key密钥没设置或配置错位检查 env_key 对应的环境变量是否已导出404 /v1/v1/xxxbase_url 重复携带路径base_url 只写域名不带 /v1429 / timeout上游限流或并发过高降低并发、错峰调用、检查余额套餐切了 CC Switch 没生效shell 里的环境变量覆盖了配置统一配置入口切换后检查 env 残留这张表看着简单但每一条我都实际遇到过。它们的共性是报错都出现在“配置边界”而不是工具核心逻辑上。所以我的第一条建议永远是——先看配置再看日志最后才去问搜索引擎。6.2 几个让日常使用更省心的操作习惯最后分享几个我的实操习惯不算高级但确实帮我少踩了很多坑。第一在 shell 里定义切换函数替代手改环境变量。我常用的是claude-ds() { export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN${DEEPSEEK_API_KEY} export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat claude } claude-official() { unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL ANTHROPIC_SMALL_FAST_MODEL ANTHROPIC_API_KEY claude }这样在终端里想走哪个后端一个命令就切换干净不会出现半清不楚的变量残留。第二工具链升级要有节制。Claude Code 和 Codex 的版本迭代都很快重要项目一旦用顺手了就别频繁升级大版本。先看看 changelog 再决定至少要把配置文件的兼容性变化看明白。我见过同事升级后 settings.json 里的字段失效整个权限策略静默回到默认值排查了很久才发现是版本行为变了。第三排错时把“模型名、协议类型、base_url、密钥来源”这四件事一次性打印出来。Claude Code 用/statusCodex 用 verbose 启动两边都用命令确认版本。很多时候报错其实只是 base_url 少个斜杠或多了一段路径这类肉眼可见的问题用日志一照就现形。第四给团队写一份极简 README写明“装哪个版本、密钥放哪、哪些文件禁止提交、默认用哪个后端”。这份文档的价值在有人加入或换机器的时候才会体现出来但它确实是整个配置体系里最值得花二十分钟写的东西。这套“官方工具 第三方模型 切换工具”的组合我用下来的整体感受是它们本质上都是配置文件驱动的客户端只要理解了 base_url、密钥、模型名、协议四个要素八成的问题都能自己定位剩下的无非是去服务商文档里核对端点和限流策略。希望这篇能帮你少走几段弯路把时间留给真正值得折腾的代码本身。
最近身边不少同事都在同时折腾两件事装 Claude Code、装 Codex。原因也直白——写代码这件事正在从“编辑器里的补全”转向“终端里的 Agent 直接接管”这两套官方命令行工具是目前走得最前的两个代表。但大多数人卡的位置几乎一模一样官方登录通了却碰上账号可用地区的校验提示默认模型配额不够用想接 DeepSeek 这类第三方模型又搞不清 ANTHROPIC_BASE_URL 和 config.toml 里的 model_provider 到底怎么填配置理顺之后CC Switch 这类多配置切换工具还会抛来一串“本地转发通道失败”的错误看着跟天书一样。这篇文章把我最近几周的实测路径完整写下来从官方安装、登录验证、VSCode 集成到接入第三方模型再到 CC Switch 的坑怎么排最后补上 Skills、超长上下文和团队配置这些进阶用法。适合两类读者一类是刚下载 CLI 还没跑通第一句对话的新手另一类是想把官方工具和第三方模型服务统一管理起来的老手。1. 先搞清楚两套 CLI 的脾气Claude Code 与 Codex 的定位差距1.1 一句话描述这两个工具Claude Code 是 Anthropic 官方的终端编码 Agent核心玩法是在终端里用自然语言下指令它自己读代码、改文件、跑命令你只需要盯着 diff 和审批请求。Codex 是 OpenAI 官方的同类工具思路几乎一样默认接的是 GPT-5.x 系列模型订阅了 ChatGPT Plus 及以上套餐就能用也支持带自己的 OpenAI API Key。这两个工具同时装在同一台机器上完全不冲突配置文件、登录态、CLI 命令都是独立的。麻烦的是它们对“第三方模型”的接入方式差得比较远网上很多教程把两者混着讲照着抄就容易出现“在 Claude Code 里找 config.toml、在 Codex 里找 ANTHROPIC_BASE_URL”这类错位操作。所以第一步不是装工具而是把它们的配置入口记清楚。1.2 账号体系、计费模型和模型路线的差异我把两者最关键的差异整理成了表格后面所有排错都能回到这张表对比项Claude CodeCodex官方登录Claude.ai 订阅账号OAuth或 Anthropic API KeyChatGPT 账号OAuth或 OpenAI API Key默认模型路线Opus / Sonnet 系列GPT-5.x Codex 系列第三方兼容端点走 Anthropic 兼容协议靠环境变量注入走 OpenAI 兼容协议靠 config.toml 的 model_provider配置文件~/.claude/settings.json、项目 .claude/settings.json~/.codex/config.toml扩展机制Skills、Subagents、MCP、HooksMCP、Agents SDK、云端任务典型报错region 不可用提示auth token 不可用、model not supported这张表的核心信息是Claude Code 的第三方接入依赖的是“Anthropic 兼容端点”比如 DeepSeek 官方提供的 /anthropic 接口Codex 的第三方接入依赖的是“OpenAI 兼容端点 /chat/completions”。两者协议不同工具调用格式也不同所以不存在一个配置两边通用的说法。后面第三章会分别展开。还有一个容易被忽略的点这两套 CLI 的“官方账号登录”和“API Key 调用”在内部是两个体系报错样式完全不同。账号体系报的是登录态、配额、区域校验API Key 体系报的是 401、余额、模型不存在。你拿到一条报错先判断它来自哪一层再动手查比到处搜错误码高效得多。2. 官方安装与登录实践从 npm 到桌面版再到 VSCode 插件2.1 Claude Code 的官方安装路径Claude Code 最省心的安装方式是 npm 全局安装前提是机器上有 Node.js。我的建议是 Node 版本至少 18最好用 20 以上的 LTS旧版本的 Node 在解析一些新语法时会出奇怪的问题而且报错信息不会直接告诉你“你的 Node 太老”。node -v npm -v npm install -g anthropic-ai/claude-code claude --versionUbuntu 上最常见的坑是 npm 全局目录权限不足报一串 EACCES。如果你是用 nvm 装的 Node一般不会遇到如果是系统包管理器装的 Node出现权限报错时别急着加 sudo先执行npm config get prefix看看全局目录再决定是修目录权限还是换用 nvm。理由是sudo 装全局包会把 package 文件变成 root 所有之后任何用户级更新都容易碰壁长期看是给自己埋雷。Windows 上除了 npm 安装官方还提供桌面版应用也叫 Claude Code 桌面版。桌面版本质上是把 CLI 包了一层壳好处是登录流程、自动更新、配置管理都在图形界面里完成对不熟悉命令行的同事友好很多。我实测下来桌面版和 CLI 共用的还是同一套配置文件你在桌面版里切换的 model回到终端里跑 claude 一样生效。官方桌面版从官网下载就好尽量别用第三方转载的安装包安全性没法保证。Linux 桌面版目前在部分发行版上有Ubuntu 用户如果不想折腾桌面版直接用 CLI 反而更顺手。安装完成后执行claude login浏览器会跳出 OAuth 授权页登录你的 Claude.ai 账号即可如果你只有 API Key也可以不登录直接export ANTHROPIC_API_KEYsk-ant-你的key claude这里要提醒一句如果你打算以第三方模型为主就不要混着设官方 API Key 和 ANTHROPIC_BASE_URL。环境变量之间存在覆盖关系两个都设的时候CLI 会优先用 BASE_URL 指向的服务但部分子命令仍会尝试用官方 Key 做校验结果就是你看到“一会儿通一会儿不通”的诡异现象。我后面的做法是用第三方模型时专门开一个干净的终端把官方变量全部 unset 掉。2.2 区域校验提示跟“安装失败”是两回事很多人在安装后第一次登录时看到类似 “note: claude code might not be available in your country. check supported countries” 的提示第一反应是安装包有问题。其实安装包没问题这是客户端的账号区域校验官方会根据账号归属地、支付方式等因素判断你当前是否在支持范围内。这个问题在官方文档里有明确的 supported countries 列表先核对账号资料里的地区和账单地址是否真实一致。我的建议比较简单如果确认账号信息没问题可以找官方支持渠道确认如果确实不在支持范围就别去碰那些灰色手段——一是违反服务条款二是靠不住三是账号一旦被封损失远大于省下的那点功夫。更务实的路线是直接走“API Key 第三方模型”这条路也就是第三章讲的内容。这条路对官方 CLI 本身没有任何影响照样能把 Claude Code 用得像模像样。2.3 Codex 的安装、登录和 auth token 报错Codex CLI 一样是 npm 包npm install -g openai/codex codex --version首次运行codex或执行codex login会走 ChatGPT 账号的 OAuth 登录部分地区的账号还需要短信验证码。热词里那个“codex手机号验证”指的就是这一步。正常情况下按官方流程绑定手机号、收验证码就能过如果你绑定的号码收不到码先检查账号本身是否处于正常状态别重复发送把验证码频控触发得更高。登录完成后Codex 会把凭证写到~/.codex/auth.json。于是有个很典型的报错codex auth token is unavailable。这个报错我见过三种触发场景本质都是“CLI 拿不到有效凭证”根本没有登录过auth.json 不存在在 SSH、CI、无头服务器这类非交互环境里OAuth token 流程走不了你同时设置了 OPENAI_API_KEY 环境变量但部分子命令仍坚持去读 auth.json。处理方法交互终端里重新codex loginCI 环境改用 API Key即设置 OPENAI_API_KEY 并把 config.toml 里的 provider 指到 openai如果确认是 auth.json 损坏备份后删掉再重新登录。注意 auth.json 里是明文 token千万别提交进 git。Codex 也有官方桌面应用和 IDE 扩展登录方式与 CLI 一致桌面版适合不想碰命令行的场景。2.4 VSCode 里同时挂两个助手Claude Code 在 VSCode 里有官方扩展安装后用同一个账号授权就能在侧边栏直接对话它本质上是调用你已经装好的 CLI所以之前说的环境变量配置同样生效。Codex 也有官方 VSCode 扩展安装后在面板里登录 ChatGPT 账号即可。同一个工作区同时启用两个扩展我不反对但有两个实操提醒。其一它们各自维护上下文你不要指望 Codex 面板里聊到一半的内容能无缝转到 Claude Code 里继续跨工具接续上下文目前只能靠你手动把关键结论粘贴过去。其二两者默认的权限控制都比较保守会逐个请求批准文件读写和命令执行如果你赶时间很容易想开全自动模式但生产仓库我强烈建议保持默认审批全自动模式在 CI 或沙箱环境里玩一玩可以本地仓库一旦误删文件后悔都来不及。3. 接入第三方模型把 DeepSeek 这类服务变成主力后端3.1 为什么要把模型换成第三方这个问题几乎每个折腾的人都问过。我总结下来就三个动机成本、区域可用性、模型偏好。官方订阅账号有配额限制重度使用很快就到天花板API 按量计费对高频短任务反而更划算。区域问题前面说过了官方账号不可用的时候第三方模型服务是另一条可行的路径——只要你使用的是该服务商公开提供的 API 和端点并且遵守它的使用条款。模型偏好就纯粹是个人口味了有些场景下第三方模型的推理表现确实更符合一些开发者的习惯。理解第三方接入的关键在于CLI 本身不会变变的只是“base_url 指向谁”和“认证 token 用谁的”。Claude Code 和 Codex 都内置了这种可配置性这也是它们能接第三方模型的原因。3.2 Claude Code 接 DeepSeek首选 Anthropic 兼容端点DeepSeek 官方提供了一个 Anthropic 兼容端点地址是 https://api.deepseek.com/anthropic模型名用 deepseek-chat 或 deepseek-reasoner。这等于官方替你做掉了协议翻译层Claude Code 连中间件都不用装三个环境变量搞定export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKENsk-你的DeepSeekKey export ANTHROPIC_MODELdeepseek-chat # 后台小任务生成标题、总结、判断是否需要工具可以指定更快更省的模型 export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat claude为什么用 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY因为这是第三方兼容端点的通用约定AUTH_TOKEN 被当作 Bearer token 原样交给服务端鉴权而 API_KEY 触发的是一些官方专用的校验逻辑用在第三方服务上容易出莫名奇妙的问题。DeepSeek 的 /anthropic 端点自己也建议用 AUTH_TOKEN照着做就行。设置完执行claude进去后敲/status看一眼 Current Model 和 API endpoint确认指向的是 DeepSeek 而不是官方。然后随便让它改一个小函数看返回速度、工具调用是否正常。我实测 DeepSeek 这个端点的工具调用是能跑通的但如果你遇到工具调用不稳定的情况第一反应应该是去查 DeepSeek 官方文档里关于 Anthropic 兼容端点的限制说明而不是怀疑 CLI 坏了。如果某家模型服务商只有 OpenAI 兼容端点、没有 Anthropic 兼容端点那 Claude Code 直接连就绕不过协议差异了。这种情况通常需要中间层做协议转换社区里有不少路由类工具。我的个人意见是能不用中间层就不用每多一层排错就多一层黑盒尽量选那些官方自带了 Anthropic 兼容端点的服务商。3.3 Codex 接 DeepSeekconfig.toml 里的 model_providerCodex 对第三方模型的支持是原生的核心配置在~/.codex/config.toml。DeepSeek 是 OpenAI 兼容协议所以 wire_api 要写 “chat”而不是 OpenAI 官方最新的 “responses”。一个可以直接用的最小配置# ~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat然后导出 key 并启动export DEEPSEEK_API_KEYsk-你的DeepSeekKey codex这里解释一下每个字段的用意。model 决定请求体里带上什么模型名必须是 provider 真实支持的model_provider 指向下方定义的 provider 块base_url 只填服务商的主域名或明确给的 API 域名别画蛇添足加 /v1否则请求路径可能变成 /v1/v1/chat/completions 这种双路径env_key 告诉 CLI 从哪个环境变量读取密钥让密钥不必硬编码进配置文件wire_api 则是协议开关DeepSeek 这类只实现了 chat 的服务必须写 “chat”。如果你同时保留官方的 OpenAI 配置建议用 profile 做隔离model gpt-5.1-codex model_provider openai [profiles.deepseek] model deepseek-chat model_provider deepseek [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 wire_api responses env_key OPENAI_API_KEY [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com wire_api chat env_key DEEPSEEK_API_KEY之后想用哪套就哪套交互式codex默认走官方配置需要切换到第三方时启动命令加--profile deepseek即可比反复改配置文件省事得多。3.4 模型名和协议不匹配的那些经典报错用第三方模型时两类报错出现频率最高。第一类跟你设置的模型名有关。Codex 默认会带上官方模型名比如请求体里出现 gpt-5.x 系列第三方服务端根本认不出来于是上游返回类似the gpt-5.6-sol model is not supported when using codex with a...的错误。这个报错不是 Codex 的 bug是上游在告诉你“你别拿 OpenAI 的模型名来问我。”解法就是改 model 字段把它换成 deepseek-chat 或 deepseek-reasoner 这类服务商真实支持的模型名。第二类跟协议有关。OpenAI 的 responses API 和 chat completions 对工具调用的结构化方式完全不同第三方如果没有实现 /responses 端点而你还把 wire_api 设成 “responses”那请求一到就失败。这类错误的特征是会出现在第一次工具调用前后而不是第一句对话。把 wire_api 改成 “chat” 之后请求会改走 /chat/completions绝大多数 OpenAI 兼容服务商都能正常响应。4. 用 CC Switch 统一管理多套配置本地转发报错的定位过程4.1 CC Switch 解决了什么问题当你同时有官方账号、DeepSeek、其他模型服务商好几套配置时每换一次都要手动改环境变量或编辑配置文件迟早出错。CC Switch 这类图形化切换工具解决的就是这个把多套“供应商配置”做成可视化的 profile一键切换它还会在本地起一个转发通道把多个后端的请求统一收口让那些只认固定 base_url 的工具也能动态选择后端。需要说明的是CC Switch 不改变任何协议规则它只是配置管理器和转发器。你直连时连不通的切到 CC Switch 一样连不通CC Switch 只是让你切换方便并不会魔法般地修复 wire_api 或模型名的问题。很多报错其实在直连时同样存在只是被 CC Switch 的一层转发包装成了更吓人的错误信息。4.2 复现一次“本地转发通道处理 codex 端点失败”的完整排查链路先说那个高频报错原文大意是cc switch 的本地转发通道在处理 codex 的 /responses 端点时连接失败。热词里那条 cc switch 处理 codex /responses 报错说的就是它。我看到这条信息的第一反应不是查网络而是先把它拆成两个问题谁在访问 /responses以及本地转发把请求转给谁、对方认不认 /responses我的排查链路是这样的你可以照着复现第一步先确认触发场景。这个报错几乎只在 Codex 配置下出现Claude Code 配置走的是另一套路径。如果你是在 CC Switch 里选了某个 Codex profile 后启动codex第一条请求就报这个说明请求已经到达 CC Switch 的本地转发通道问题出在转发通道到上游的环节。第二步打开 CC Switch 的日志和 codex 的详细输出。Codex 侧可以开 verbose 模式CC Switch 侧看日志面板。重点看转发通道实际请求的上游 URL 和 HTTP 状态。我遇到过的情况是上游返回 404/not implemented因为转发通道把请求按 /responses 路径转发过去而上游根本不提供这个端点。第三步检查 wire_api。Codex 默认走 responses 协议所以请求路径是 /responses。DeepSeek 等第三方大多只实现了 /chat/completions没有 /responses。你需要让 Codex 走 chat 协议要么在 config.toml 里把 provider 的 wire_api 改成 “chat”要么在 CC Switch 的 provider 配置里选对协议类型。改完之后转发通道发出的路径会变成 /chat/completions问题通常当场消失。第四步再检查模型名。协议对了之后如果请求体里还是 Codex 默认的官方模型名上游会继续报 model not supported。把 model 强制设成 deepseek-chat两边就对齐了。第五步查偶发因素。端口被占用、base_url 配置里带了多余的路径前缀、上游限流返回 429这些都会让转发通道报连接失败。日志里 HTTP 状态码 404 和 429 的修法完全不同一定要先看状态码再动手。这套链路走完之后可以下一个结论这个报错九成以上是“协议类型 模型名”两者之一没对齐跟网络没有关系。还有一成是 base_url 路径写错属于手滑。4.3 一个容易被忽略的配置归属问题CC Switch 在切换供应商时是通过改写配置文件来实现的。Claude Code 这边它改的是 settings.json 里的环境变量块Codex 这边它会调整 config.toml。问题来了如果你在 shell 的 .bashrc 里显式 export 了 ANTHROPIC_BASE_URL 或 OPENAI_BASE_URL 这类变量这些外部环境变量会跟 CC Switch 写进配置的变量打架结果就是“我在 CC Switch 里明明切了 DeepSeek终端里跑起来还是官方”。我个人踩过这个坑之后定的规矩是同一个工具的配置入口只用一个。要么全部靠 CC Switch 管理要么全部写在 shell 配置里不要两处都写。如果一定要混用每次切换后开一个新终端并且先用env | grep -i anthropic检查残留变量确认没有旧变量盖掉新配置。5. 把官方能力用透Skills、超长上下文与团队配置5.1 手动安装 GitHub 上的 SkillsClaude Code 的 Skills 本质上就是“文件夹 一份 SKILL.md”。官方生态里有大量开源 skill 躺在 GitHub 上手动安装一点都不复杂。以用户级安装为例mkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/某用户/某skill仓库.git my-skill # 确认结构 ls ~/.claude/skills/my-skill/SKILL.md如果是项目级使用就放到仓库里的.claude/skills/skill-name/SKILL.md提交到 git 后整个团队都能共享。SKILL.md 的骨架大致是--- name: my-skill description: 在改某类文件、处理某类任务时使用给模型判断触发时机 --- # 执行步骤 1. 先读取相关文件 2. 按模板生成内容 3. 运行校验命令 # 注意事项 - 关键禁忌写在这里最容易被忽略的是 frontmatter 里的 description。它决定了模型会不会自动调用这个 skill写作重点是“在什么场景下、遇到什么任务时使用”而不是“这个 skill 多厉害”。安装完以后重启 claude用/skills能看到列表就算成功。Codex 侧目前没有和 Claude Skills 完全对等的目录式机制它的扩展更多走 MCP 和 Agents SDK所以这条主要针对 Claude Code。5.2 1M 上下文并不是默认开启的Claude Code 的超长上下文功能也就是热词里那个“claude code 1m上下文”是个很有吸引力的卖点。但要注意两点不是所有模型都支持 1M 上下文支持也需要在配置里显式开启。通常的做法是参考官方文档在 settings.json 里打开对应 experimental 项或者直接在/config菜单里找 1M Context 的开关。具体字段名在不同版本里有差异以你手上版本的提示为准我不建议照抄网上的旧配置很容易失效。1M 上下文能解决的是“整仓分析”这类场景——把整个代码库喂进去让它跨目录找关联、做大规模重构。但我不建议把日常小改动也丢进超长上下文里因为长上下文的推理时间、费用、响应首字时间都会明显上升很多小任务用默认窗口反而更快。另外上下文再长也有输出截断的风险超大上下文场景下更要习惯让它分步输出而不是指望一次把所有事情干完。5.3 一份可以提交到仓库的团队配置样例Claude Code 和 Codex 都支持把配置放进仓库这对团队统一行为很有用。Claude Code 侧建议在项目根目录放.claude/settings.json用 permissions 控制允许/拒绝的操作用 hooks 在特定命令执行前做拦截。一个不那么激进、适合起步的示例{ permissions: { allow: [ Read(workspace), Edit(workspace), Bash(git status), Bash(git diff), Bash(npm run lint) ], deny: [ Bash(rm -rf *), Bash(git push --force) ] }, hooks: { PreToolUse: [ { matcher: Bash(git push*), hooks: [ { type: command, command: echo push 操作已记录 /tmp/claude_hook.log } ] } ] } }这套配置的意思是Agent 读写仓库和跑常用命令不需要逐个询问但危险命令直接拒绝。注意别把密钥写进这种会被提交的文件环境变量和 key 一律走本地的 settings.local.json 或 shell 环境。Codex 侧把~/.codex/config.toml纳入 dotfiles 管理即可但前面说过~/.codex/auth.json属于凭证文件无论如何都不要提交。一个简单的 gitignore 规则可以避免手滑echo auth.json ~/.codex/.gitignore6. 高频报错速查表与我的实操建议6.1 一张表解决八成求助帖把这几周收集到的、群里同事问过的高频报错汇总成一张速查表每次看到同类问题直接对照报错/现象真实原因处理建议note: claude code might not be available in your country账号地区/支付校验不通过核对官方支持列表不碰灰色手段改用 API Key 或第三方模型codex auth token is unavailable未登录或凭证缓存失效交互环境重新 codex loginCI 用 OPENAI_API_KEY本地转发通道处理 codex /responses 失败wire_api 仍是 responses上游只支持 chat把 provider 的 wire_api 改成 chatthe gpt-5.6-sol model is not supported上游不认识官方模型名将 model 改为 deepseek-chat 等上游支持的模型401 unauthorized / invalid api key密钥没设置或配置错位检查 env_key 对应的环境变量是否已导出404 /v1/v1/xxxbase_url 重复携带路径base_url 只写域名不带 /v1429 / timeout上游限流或并发过高降低并发、错峰调用、检查余额套餐切了 CC Switch 没生效shell 里的环境变量覆盖了配置统一配置入口切换后检查 env 残留这张表看着简单但每一条我都实际遇到过。它们的共性是报错都出现在“配置边界”而不是工具核心逻辑上。所以我的第一条建议永远是——先看配置再看日志最后才去问搜索引擎。6.2 几个让日常使用更省心的操作习惯最后分享几个我的实操习惯不算高级但确实帮我少踩了很多坑。第一在 shell 里定义切换函数替代手改环境变量。我常用的是claude-ds() { export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN${DEEPSEEK_API_KEY} export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat claude } claude-official() { unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL ANTHROPIC_SMALL_FAST_MODEL ANTHROPIC_API_KEY claude }这样在终端里想走哪个后端一个命令就切换干净不会出现半清不楚的变量残留。第二工具链升级要有节制。Claude Code 和 Codex 的版本迭代都很快重要项目一旦用顺手了就别频繁升级大版本。先看看 changelog 再决定至少要把配置文件的兼容性变化看明白。我见过同事升级后 settings.json 里的字段失效整个权限策略静默回到默认值排查了很久才发现是版本行为变了。第三排错时把“模型名、协议类型、base_url、密钥来源”这四件事一次性打印出来。Claude Code 用/statusCodex 用 verbose 启动两边都用命令确认版本。很多时候报错其实只是 base_url 少个斜杠或多了一段路径这类肉眼可见的问题用日志一照就现形。第四给团队写一份极简 README写明“装哪个版本、密钥放哪、哪些文件禁止提交、默认用哪个后端”。这份文档的价值在有人加入或换机器的时候才会体现出来但它确实是整个配置体系里最值得花二十分钟写的东西。这套“官方工具 第三方模型 切换工具”的组合我用下来的整体感受是它们本质上都是配置文件驱动的客户端只要理解了 base_url、密钥、模型名、协议四个要素八成的问题都能自己定位剩下的无非是去服务商文档里核对端点和限流策略。希望这篇能帮你少走几段弯路把时间留给真正值得折腾的代码本身。
