近两年AI 编程助手从聊天窗口走进了终端。OpenAI 推出 CodexAnthropic 推出 Claude Code开发者在命令行里就能让模型读取项目、生成补丁、执行测试。网上有一个流传的说法是“OpenAI 之后又是 AnthropicClaude 将攻击延伸至公共互联网”。很多人看到“攻击”两个字会往网络安全方向联想但在实际工程语境里这句话通常描述的是同一个现象编码助手的触角从本地终端延伸到了远程 API 和公共互联网服务。也就是说你的 CLI 工具不再只是本地脚本它会通过 HTTPS 调用类似 api.anthropic.com 这样的公共端点把项目上下文发送到模型服务端再把结果同步回终端。这个变化带来了安装、鉴权、模型接入、错误排查和安全管理等一系列新问题。这篇文章会以 Claude Code 为主线同时对照 OpenAI Codex完整梳理一套可复现的接入方法并给出生产环境下的使用边界。1. 先理解编码助手从本地终端走向公共互联网的边界1.1 Claude Code 与 OpenAI Codex 到底是什么Claude Code 是 Anthropic 推出的终端编码助手。与网页版 Claude 不同它不是一问一答的聊天框而是在你项目目录里运行的一个交互式程序它会读取文件、运行命令、调用语言模型 API并根据模型返回的计划继续执行。OpenAI Codex 也是类似定位提供命令行编码助手支持在终端里接受自然语言任务编译执行、查看错误、提交补丁。从技术上可以这样概括CLI Agent以命令行为主体交互方式模型可以获取终端输出也可以发起新的命令。工具调用模型不只生成文本还会请求执行 shell 命令、读取文件、修改文件、运行测试。审批模式执行敏感操作前需要用户确认避免模型在项目目录里做不可控的变更。这类工具的价值在于它把“模型理解代码”和“机器执行操作”连成了一条链路。你给它一个目标它自己决定先看哪个目录再改哪个函数最后跑一下测试。相比复制粘贴到网页聊天框这种工作方式更接近真实开发流程。1.2 “攻击延伸至公共互联网”在工程上指什么如果把“攻击”理解成网络攻击方向就错了。这里说的“延伸至公共互联网”本质是请求从本机发往公共 API。Claude Code 自己并没有完整的大模型参数它需要把当前项目上下文、用户指令和工具输出发送到 Anthropic 的服务端等待模型推理结果返回。OpenAI Codex 也一样需要连接 OpenAI 或 Codex 服务。这段调用链路有几个工程边界需要注意数据离开本地项目代码片段、日志、命令输出会进入模型服务商的处理管道。鉴权发生在客户端与公共端点之间API Key 或登录令牌决定你是否有权限调用。网络连通性影响一切DNS 解析失败、TLS 握手异常、防火墙拦截都可能让整个工具不可用。服务端状态不可见模型是否升级、接口是否限流、账户是否有欠费你只能通过返回状态码和日志判断。理解这条边界后后面所有配置和排错才有一个清晰的切入角度。1.3 两种工具的定位对比维度Claude CodeOpenAI Codex开发方AnthropicOpenAI主要形态终端 CLI、VS Code 扩展终端 CLI、IDE 集成常见安装入口npm 包、官方安装器npm 包、GitHub 发布物远端 APIapi.anthropic.comOpenAI Codex 服务典型场景项目重构、批量修改、终端内调试代码生成、任务自动化、命令行补全授权方式API Key 或账号登录浏览器登录或 API Key这个对比不是让你二选一而是说明它们是同一个技术方向上的两种实现。掌握了 Claude Code再切到 OpenAI Codex很多概念是相通的。2. 环境准备版本、账号与 API 凭据2.1 运行环境检查先确认本机环境是否满足要求。Claude Code 的 npm 安装方式依赖 Node.jsOpenAI Codex 也提供 npm 安装路径。不同版本对 Node 版本要求会有差异但建议至少使用当前 LTS 或更高版本。node -v npm -v git --version如果node -v输出类似 v18.20.4说明 Node 环境正常。如果提示找不到命令需要先安装 Node.js。Git 不是 CLI 工具本身必需的依赖但 Claude Code 在分析项目时经常依赖 Git 状态来判断改动范围所以也建议提前安装。这里有一个常见误区只装了 Node但没有把 npm 全局安装目录加入 PATH。后文安装完成后再执行claude就很可能出现“不是内部或外部命令”的报错。2.2 获取 Anthropic 与 OpenAI 的 API KeyAnthropic 的 API Key 在 Anthropic Console 中创建通常流程是登录 Anthropic Console。进入 API Keys 页面。创建新的 API Key。复制并保存到本地环境变量。OpenAI 的 API Key 在 OpenAI Platform 中创建路径是 API keys 页面登录 OpenAI Platform。进入 API keys。点击 Create new secret key。保存生成的密钥。无论使用哪家都要遵守一个底线不要把 Key 提交到 Git 仓库不要写在配置文件里随项目分发不要复制到聊天群或公开文档。API Key 是计费凭证泄露后可能被他人直接消耗额度也会带来数据访问风险。2.3 用环境变量管理密钥在 Linux 或 macOS 下可以在~/.zshrc或~/.bashrc中追加export ANTHROPIC_API_KEY你的-Anthropic-Key export OPENAI_API_KEY你的-OpenAI-Key在 Windows PowerShell 下可以执行$env:ANTHROPIC_API_KEY你的-Anthropic-Key $env:OPENAI_API_KEY你的-OpenAI-Key常用环境变量如下变量名作用说明ANTHROPIC_API_KEYClaude Code 访问 Anthropic API 的密钥必填除非使用账号登录或第三方兼容层ANTHROPIC_MODEL指定主模型不设置时使用 CLI 内置默认模型ANTHROPIC_BASE_URL覆盖 API 基础地址接入兼容服务层或本地模型时使用ANTHROPIC_AUTH_TOKEN自定义认证令牌使用兼容服务层时可替代 API KeyOPENAI_API_KEYCodex 访问 OpenAI 服务的密钥登录授权时可不填OPENAI_BASE_URL覆盖 OpenAI 接口地址接入第三方或本地兼容服务时使用要注意环境变量只在当前会话生效。如果你关闭终端后变量丢失说明没有写进 shell 配置文件需要重新加载配置或直接写入profile文件。推荐做法在项目中创建.env文件保存非敏感的非密钥配置密钥仍然放在系统环境变量或密钥管理服务中并确保.env被.gitignore忽略。3. 安装 Claude Code 与 OpenAI Codex3.1 安装 Claude Code 的常见方式Claude Code 最常见的安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后检查版本claude --version如果能看到版本号说明安装成功。如果提示找不到命令执行npm prefix -g把输出的目录确认是否正确加入 PATH。在 Windows 上还需要确认 npm 全局 bin 目录在系统 PATH 中。除了 npmAnthropic 也提供原生安装器。原生安装的好处是不依赖 Node 运行时升级方式通常是直接执行 CLI 自带的更新命令。不同平台的安装命令存在差异实际使用时以官方文档为准。重点是要避免同时用 npm 和原生安装器装了同一个工具的多个版本否则会出现“明明刚安装命令却不是我预期的版本”的问题。Claude Code 还有桌面版和 VS Code 扩展。桌面版本质上是给 CLI 提供了一个图形入口VS Code 扩展则把对话和文件操作集成到编辑器侧边栏。它们的核心仍然是同一个 CLI因此不需要重复安装核心命令。3.2 安装 OpenAI Codex 的常见方式OpenAI Codex 同样可以通过 npm 安装npm install -g openai/codex安装后验证codex --version也可以从 GitHub 上的官方仓库下载预编译二进制。仓库地址是github.com/openai/codex具体安装方式应阅读对应版本 README因为不同系统、不同版本提供的包名和命令参数会变化。OpenAI Codex 支持浏览器授权登录执行codex login它会打开浏览器完成授权。这种方式的优势是访问令牌由官方服务管理比在终端里粘贴长密钥更安全也更方便撤销。3.3 安装后验证与常见现象安装完成后先运行帮助命令确认基础环境claude --help codex --help--help能正常输出说明二进制文件本身没问题后续报错大概率出在 API Key、网络或模型配置上。常见现象包括claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。以及claude 不是内部或外部命令也不是可运行的程序或批处理文件。这两个报错的原因基本都是 PATH 没有配置好或者 npm 安装没有真正成功。解决办法先执行npm list -g --depth0看包是否在列表里再检查 PATH。4. 接入第三方模型或本地模型以 DeepSeek、Ollama 和 vLLM 为例4.1 为什么需要接入第三方模型或本地模型很多开发者不希望把项目代码全部发送到外部模型服务或者在测试阶段想验证不同模型的效果又或者单纯因为某些业务的成本限制需要把 Claude Code 接到第三方模型甚至本地模型上。这是合理的工程需求。但要注意一个前提Claude Code 默认使用 Anthropic Messages API。你接入的第三方服务必须能解析 Anthropic API 格式或者通过兼容服务层把请求转换成 OpenAI 格式或本地模型能够理解的格式。这不是“把 OpenAI 的地址填进去就行”的事情。4.2 用环境变量指向兼容服务层当接口地址需要改变时设置export ANTHROPIC_BASE_URLhttps://your-gateway.example.com export ANTHROPIC_AUTH_TOKENyour-token export ANTHROPIC_MODELcompatible-model-name这里的your-gateway.example.com是你自己部署或购买的一个 API 兼容服务层地址。它的作用是把 Anthropic Messages API 转成下游模型能识别的协议。如果你直接把ANTHROPIC_BASE_URL指向一个纯 OpenAI 兼容端点而该端点没有转换能力CLI 会在请求头或请求体解析阶段报错而不是等到模型推理阶段才失败。注意事项ANTHROPIC_BASE_URL改动影响的是所有请求。生产环境建议把默认官方地址、第三方地址和本地地址分开配置在不同环境变量中避免在同一个环境里来回切换。4.3 接入 DeepSeek 等第三方模型DeepSeek 平台提供 OpenAI 兼容接口。因此把 Claude Code 接到 DeepSeek 的典型路径是获取 DeepSeek 的 API Key。部署或使用一个能完成 Anthropic 到 OpenAI 协议转换的兼容服务层。在兼容服务层中配置 DeepSeek 模型映射。在 Claude Code 中通过ANTHROPIC_BASE_URL指向兼容服务层。模型名映射是这个过程中最容易出错的部分。如果兼容服务层把 Claude Code 传来的模型名原样转发给 DeepSeek但该模型名不在 DeepSeek 接口的白名单里就会看到类似这样的报错deepseek-v4-pro is not a model this version of claude code recognizes这个报错并不是说下游模型不存在而是说 Claude Code 当前版本的模型校验名单里不包含这个名字。解决思路有两个方向升级 Claude Code看新版本是否支持目标模型名。在兼容服务层做模型名映射把 Claude Code 请求中的模型 ID 替换成下游模型实际可用的 ID。不要试图通过硬改版本或关闭校验来绕过检查因为模型名不一致还会影响请求参数格式更可能造成上下文长度和工具调用协议不匹配。4.4 本地模型Ollama 与 vLLM 部署示例如果你希望完全在本地运行可以先启动一个 OpenAI 兼容的服务再把它接到兼容服务层。Ollama 适合个人电脑快速体验ollama serve ollama pull llama3.1vLLM 适合有一定 GPU 资源的服务器命令大致如下vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000命令中的模型名和端口要按实际环境替换。启动后本地服务会暴露一个 OpenAI 兼容端点默认地址通常是http://localhost:8000/v1。但 Claude Code 并不能直接消费这个 OpenAI 兼容端点。它发送的是 Anthropic API 格式。所以完整链路应该是Claude Code - ANTHROPIC_BASE_URL 指向兼容服务层 - 兼容服务层把 Anthropic 请求转成 OpenAI 请求 - OpenAI 格式请求打到 Ollama 或 vLLM这种架构并不复杂但你在排查问题时必须清楚每一层在干什么。否则出现请求失败时你可能分不清是 Claude Code 配置错了还是兼容服务层没启动还是本地模型没有加载成功。4.5 模型识别错误不是模型名不存在而是版本名单不匹配模型识别错误在接入第三方模型时非常常见。这里要区分三种情况现象常见原因处理方向请求发出后返回模型不存在下游模型服务没有该模型 ID在兼容服务层确认模型名称请求还没发出CLI 启动阶段就拒绝Claude Code 内置模型名单不识别升级 CLI 或做模型名映射请求能发出但工具调用失败模型不支持 Claude Code 要求的工具格式换用支持工具调用的模型或关闭需要工具调用功能很多人在第一类情况里直接修改代码硬编码模型名结果越改越乱。正确顺序是先确认是哪一层不识别再决定在哪一层修改。5. 运行验证从最小对话到实际任务5.1 最小冒烟测试环境配置完成后不要一上来就处理大型项目。先在空目录里做一个最小测试确认链路通了再说。进入一个临时目录mkdir claude-test cd claude-test claude在交互界面里输入请创建一个 hello.py 文件内容是一段读取命令行参数的 Python 脚本然后运行它验证输出。正常情况下Claude Code 会列出计划请求执行写文件命令再请求执行运行命令。你需要观察每一步是否需要确认以及最终是否生成代码。如果这一步成功说明 API Key、网络、模型参数、工具调用链路都是通的。5.2 在 VS Code 中配置 Claude CodeVS Code 扩展提供了图形化入口。安装官方扩展后需要确保系统里已经安装了 Claude Code CLI。打开任意项目在侧边栏启动会话。VS Code 扩展的优势是能看到文件树和差异视图。模型修改文件后你可以在编辑器里直接审查变更。这里比终端交互更适合做代码审查因为改动块高亮比纯文本输出更直观。配置时重点确认以下选项工作区权限是否允许模型读取全部文件。命令执行权限是否允许模型运行终端命令。自动接受模式是否开启后不再逐条确认。在个人本地环境可以放宽权限但在共享项目或生产环境里建议保持逐条确认避免模型误操作覆盖重要文件。5.3 观察请求走向与日志如果接入的是第三方或本地兼容服务层你需要确认请求真的发到了你期望的端点而不是回退到官方 API。可以使用调试模式运行claude --verbose或者claude --debug不同版本的日志开关名可能不同--verbose通常已经能输出关键步骤。日志中应能观察到请求目标地址、模型名称和基本耗时。如果看到地址仍然是官方 API说明环境变量没有在当前进程生效或者 shell 配置没有被重新加载。验证原则不要只看能不能输出文字要观察请求去往哪个端点、用了哪个模型、实际耗时是多少。只有这三个数据都对才算真正配置成功。6. 常见故障排查从现象倒推原因6.1 命令无法识别现象claude 不是内部或外部命令或无法将“claude”项识别为 cmdlet排查顺序如下检查是否安装成功npm list -g --depth0。找到全局目录npm prefix -g。把对应的 bin 目录加入 PATH。重新打开终端再执行claude --version。Windows 用户还要检查 PowerShell 执行策略。如果执行脚本被禁止官方文档通常会提供调整方法。这个问题的预防手段是在安装前就确认 npm 全局 bin 目录已经在 PATH 中。6.2 连不上 api.anthropic.com现象unable to connect to anthropic services failed to connect to api.anthropic.com这是网络层连接失败不是模型层报错。可能原因包括 DNS 解析异常、网络出口不通、TLS 被中间设备拦截、防火墙阻断。先做基础检查curl -I https://api.anthropic.com nslookup api.anthropic.comcurl能返回 HTTP 状态码说明网络通路正常如果超时说明出口被限制。nslookup能解析出域名说明 DNS 没问题如果解析失败先处理 DNS。这类问题不要反复重启 CLI要优先确认网络层。网络恢复后再尝试运行一次最小对话。注意不要把网络连接问题和账号权限问题混在一起。连接错误通常发生在请求到达服务端之前此时修复 API Key 没有意义。先确认网络层再确认鉴权层最后确认模型层。6.3 新用户不可用提示现象unfortunately, claude is not available to new users right now这个提示意味着当前账号或当前访问方式没有获得使用资格可能是订阅类型、账户状态或服务开放范围限制。解决方向是确认使用的是 API Key而不是网页端免费额度。检查账户是否绑定了有效的付费方案。查阅 Anthropic 官方文档确认当前账号所在的可用范围。联系官方支持而不是寻找非官方绕过方式。这个问题的核心是账号资格而不是技术配置。继续调整环境变量不会有效果。6.4 模型不识别现象deepseek-v4-pro is not a model this version of claude code recognizes原因和解决办法在 4.5 中已经说明。这里补充一个排查顺序先看报错发生在 CLI 启动阶段还是请求发出之后。启动阶段报错优先升级 CLI 或检查模型名映射。请求发出后报错优先检查下游模型服务实际可用模型列表。不要为了绕过这个检查而修改 CLI 内部文件。那样会导致版本升级时配置失效还会让问题更难排查。6.5 API Key 和认证错误认证类错误通常返回 401 或 403。常见原因错误现象常见原因处理建议401 UnauthorizedAPI Key 不存在、过期或格式错误重新创建 Key并确认环境变量已加载403 Forbidden账号没有该模型或接口的访问权限检查账户套餐和模型权限429 Too Many Requests请求超过限流额度降低并发等待重试窗口排查时先确认环境变量里是否有值echo $ANTHROPIC_API_KEY如果输出为空说明环境变量没有设置成功。6.6 完整排查顺序表当工具整体不可用时按下面顺序排查最快步骤检查内容验证方式1命令是否存在claude --version2环境变量是否加载echo $ANTHROPIC_API_KEY AI编程助手走进终端：Claude Code与OpenAI Codex接入实战
近两年AI 编程助手从聊天窗口走进了终端。OpenAI 推出 CodexAnthropic 推出 Claude Code开发者在命令行里就能让模型读取项目、生成补丁、执行测试。网上有一个流传的说法是“OpenAI 之后又是 AnthropicClaude 将攻击延伸至公共互联网”。很多人看到“攻击”两个字会往网络安全方向联想但在实际工程语境里这句话通常描述的是同一个现象编码助手的触角从本地终端延伸到了远程 API 和公共互联网服务。也就是说你的 CLI 工具不再只是本地脚本它会通过 HTTPS 调用类似 api.anthropic.com 这样的公共端点把项目上下文发送到模型服务端再把结果同步回终端。这个变化带来了安装、鉴权、模型接入、错误排查和安全管理等一系列新问题。这篇文章会以 Claude Code 为主线同时对照 OpenAI Codex完整梳理一套可复现的接入方法并给出生产环境下的使用边界。1. 先理解编码助手从本地终端走向公共互联网的边界1.1 Claude Code 与 OpenAI Codex 到底是什么Claude Code 是 Anthropic 推出的终端编码助手。与网页版 Claude 不同它不是一问一答的聊天框而是在你项目目录里运行的一个交互式程序它会读取文件、运行命令、调用语言模型 API并根据模型返回的计划继续执行。OpenAI Codex 也是类似定位提供命令行编码助手支持在终端里接受自然语言任务编译执行、查看错误、提交补丁。从技术上可以这样概括CLI Agent以命令行为主体交互方式模型可以获取终端输出也可以发起新的命令。工具调用模型不只生成文本还会请求执行 shell 命令、读取文件、修改文件、运行测试。审批模式执行敏感操作前需要用户确认避免模型在项目目录里做不可控的变更。这类工具的价值在于它把“模型理解代码”和“机器执行操作”连成了一条链路。你给它一个目标它自己决定先看哪个目录再改哪个函数最后跑一下测试。相比复制粘贴到网页聊天框这种工作方式更接近真实开发流程。1.2 “攻击延伸至公共互联网”在工程上指什么如果把“攻击”理解成网络攻击方向就错了。这里说的“延伸至公共互联网”本质是请求从本机发往公共 API。Claude Code 自己并没有完整的大模型参数它需要把当前项目上下文、用户指令和工具输出发送到 Anthropic 的服务端等待模型推理结果返回。OpenAI Codex 也一样需要连接 OpenAI 或 Codex 服务。这段调用链路有几个工程边界需要注意数据离开本地项目代码片段、日志、命令输出会进入模型服务商的处理管道。鉴权发生在客户端与公共端点之间API Key 或登录令牌决定你是否有权限调用。网络连通性影响一切DNS 解析失败、TLS 握手异常、防火墙拦截都可能让整个工具不可用。服务端状态不可见模型是否升级、接口是否限流、账户是否有欠费你只能通过返回状态码和日志判断。理解这条边界后后面所有配置和排错才有一个清晰的切入角度。1.3 两种工具的定位对比维度Claude CodeOpenAI Codex开发方AnthropicOpenAI主要形态终端 CLI、VS Code 扩展终端 CLI、IDE 集成常见安装入口npm 包、官方安装器npm 包、GitHub 发布物远端 APIapi.anthropic.comOpenAI Codex 服务典型场景项目重构、批量修改、终端内调试代码生成、任务自动化、命令行补全授权方式API Key 或账号登录浏览器登录或 API Key这个对比不是让你二选一而是说明它们是同一个技术方向上的两种实现。掌握了 Claude Code再切到 OpenAI Codex很多概念是相通的。2. 环境准备版本、账号与 API 凭据2.1 运行环境检查先确认本机环境是否满足要求。Claude Code 的 npm 安装方式依赖 Node.jsOpenAI Codex 也提供 npm 安装路径。不同版本对 Node 版本要求会有差异但建议至少使用当前 LTS 或更高版本。node -v npm -v git --version如果node -v输出类似 v18.20.4说明 Node 环境正常。如果提示找不到命令需要先安装 Node.js。Git 不是 CLI 工具本身必需的依赖但 Claude Code 在分析项目时经常依赖 Git 状态来判断改动范围所以也建议提前安装。这里有一个常见误区只装了 Node但没有把 npm 全局安装目录加入 PATH。后文安装完成后再执行claude就很可能出现“不是内部或外部命令”的报错。2.2 获取 Anthropic 与 OpenAI 的 API KeyAnthropic 的 API Key 在 Anthropic Console 中创建通常流程是登录 Anthropic Console。进入 API Keys 页面。创建新的 API Key。复制并保存到本地环境变量。OpenAI 的 API Key 在 OpenAI Platform 中创建路径是 API keys 页面登录 OpenAI Platform。进入 API keys。点击 Create new secret key。保存生成的密钥。无论使用哪家都要遵守一个底线不要把 Key 提交到 Git 仓库不要写在配置文件里随项目分发不要复制到聊天群或公开文档。API Key 是计费凭证泄露后可能被他人直接消耗额度也会带来数据访问风险。2.3 用环境变量管理密钥在 Linux 或 macOS 下可以在~/.zshrc或~/.bashrc中追加export ANTHROPIC_API_KEY你的-Anthropic-Key export OPENAI_API_KEY你的-OpenAI-Key在 Windows PowerShell 下可以执行$env:ANTHROPIC_API_KEY你的-Anthropic-Key $env:OPENAI_API_KEY你的-OpenAI-Key常用环境变量如下变量名作用说明ANTHROPIC_API_KEYClaude Code 访问 Anthropic API 的密钥必填除非使用账号登录或第三方兼容层ANTHROPIC_MODEL指定主模型不设置时使用 CLI 内置默认模型ANTHROPIC_BASE_URL覆盖 API 基础地址接入兼容服务层或本地模型时使用ANTHROPIC_AUTH_TOKEN自定义认证令牌使用兼容服务层时可替代 API KeyOPENAI_API_KEYCodex 访问 OpenAI 服务的密钥登录授权时可不填OPENAI_BASE_URL覆盖 OpenAI 接口地址接入第三方或本地兼容服务时使用要注意环境变量只在当前会话生效。如果你关闭终端后变量丢失说明没有写进 shell 配置文件需要重新加载配置或直接写入profile文件。推荐做法在项目中创建.env文件保存非敏感的非密钥配置密钥仍然放在系统环境变量或密钥管理服务中并确保.env被.gitignore忽略。3. 安装 Claude Code 与 OpenAI Codex3.1 安装 Claude Code 的常见方式Claude Code 最常见的安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后检查版本claude --version如果能看到版本号说明安装成功。如果提示找不到命令执行npm prefix -g把输出的目录确认是否正确加入 PATH。在 Windows 上还需要确认 npm 全局 bin 目录在系统 PATH 中。除了 npmAnthropic 也提供原生安装器。原生安装的好处是不依赖 Node 运行时升级方式通常是直接执行 CLI 自带的更新命令。不同平台的安装命令存在差异实际使用时以官方文档为准。重点是要避免同时用 npm 和原生安装器装了同一个工具的多个版本否则会出现“明明刚安装命令却不是我预期的版本”的问题。Claude Code 还有桌面版和 VS Code 扩展。桌面版本质上是给 CLI 提供了一个图形入口VS Code 扩展则把对话和文件操作集成到编辑器侧边栏。它们的核心仍然是同一个 CLI因此不需要重复安装核心命令。3.2 安装 OpenAI Codex 的常见方式OpenAI Codex 同样可以通过 npm 安装npm install -g openai/codex安装后验证codex --version也可以从 GitHub 上的官方仓库下载预编译二进制。仓库地址是github.com/openai/codex具体安装方式应阅读对应版本 README因为不同系统、不同版本提供的包名和命令参数会变化。OpenAI Codex 支持浏览器授权登录执行codex login它会打开浏览器完成授权。这种方式的优势是访问令牌由官方服务管理比在终端里粘贴长密钥更安全也更方便撤销。3.3 安装后验证与常见现象安装完成后先运行帮助命令确认基础环境claude --help codex --help--help能正常输出说明二进制文件本身没问题后续报错大概率出在 API Key、网络或模型配置上。常见现象包括claude : 无法将“claude”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。以及claude 不是内部或外部命令也不是可运行的程序或批处理文件。这两个报错的原因基本都是 PATH 没有配置好或者 npm 安装没有真正成功。解决办法先执行npm list -g --depth0看包是否在列表里再检查 PATH。4. 接入第三方模型或本地模型以 DeepSeek、Ollama 和 vLLM 为例4.1 为什么需要接入第三方模型或本地模型很多开发者不希望把项目代码全部发送到外部模型服务或者在测试阶段想验证不同模型的效果又或者单纯因为某些业务的成本限制需要把 Claude Code 接到第三方模型甚至本地模型上。这是合理的工程需求。但要注意一个前提Claude Code 默认使用 Anthropic Messages API。你接入的第三方服务必须能解析 Anthropic API 格式或者通过兼容服务层把请求转换成 OpenAI 格式或本地模型能够理解的格式。这不是“把 OpenAI 的地址填进去就行”的事情。4.2 用环境变量指向兼容服务层当接口地址需要改变时设置export ANTHROPIC_BASE_URLhttps://your-gateway.example.com export ANTHROPIC_AUTH_TOKENyour-token export ANTHROPIC_MODELcompatible-model-name这里的your-gateway.example.com是你自己部署或购买的一个 API 兼容服务层地址。它的作用是把 Anthropic Messages API 转成下游模型能识别的协议。如果你直接把ANTHROPIC_BASE_URL指向一个纯 OpenAI 兼容端点而该端点没有转换能力CLI 会在请求头或请求体解析阶段报错而不是等到模型推理阶段才失败。注意事项ANTHROPIC_BASE_URL改动影响的是所有请求。生产环境建议把默认官方地址、第三方地址和本地地址分开配置在不同环境变量中避免在同一个环境里来回切换。4.3 接入 DeepSeek 等第三方模型DeepSeek 平台提供 OpenAI 兼容接口。因此把 Claude Code 接到 DeepSeek 的典型路径是获取 DeepSeek 的 API Key。部署或使用一个能完成 Anthropic 到 OpenAI 协议转换的兼容服务层。在兼容服务层中配置 DeepSeek 模型映射。在 Claude Code 中通过ANTHROPIC_BASE_URL指向兼容服务层。模型名映射是这个过程中最容易出错的部分。如果兼容服务层把 Claude Code 传来的模型名原样转发给 DeepSeek但该模型名不在 DeepSeek 接口的白名单里就会看到类似这样的报错deepseek-v4-pro is not a model this version of claude code recognizes这个报错并不是说下游模型不存在而是说 Claude Code 当前版本的模型校验名单里不包含这个名字。解决思路有两个方向升级 Claude Code看新版本是否支持目标模型名。在兼容服务层做模型名映射把 Claude Code 请求中的模型 ID 替换成下游模型实际可用的 ID。不要试图通过硬改版本或关闭校验来绕过检查因为模型名不一致还会影响请求参数格式更可能造成上下文长度和工具调用协议不匹配。4.4 本地模型Ollama 与 vLLM 部署示例如果你希望完全在本地运行可以先启动一个 OpenAI 兼容的服务再把它接到兼容服务层。Ollama 适合个人电脑快速体验ollama serve ollama pull llama3.1vLLM 适合有一定 GPU 资源的服务器命令大致如下vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000命令中的模型名和端口要按实际环境替换。启动后本地服务会暴露一个 OpenAI 兼容端点默认地址通常是http://localhost:8000/v1。但 Claude Code 并不能直接消费这个 OpenAI 兼容端点。它发送的是 Anthropic API 格式。所以完整链路应该是Claude Code - ANTHROPIC_BASE_URL 指向兼容服务层 - 兼容服务层把 Anthropic 请求转成 OpenAI 请求 - OpenAI 格式请求打到 Ollama 或 vLLM这种架构并不复杂但你在排查问题时必须清楚每一层在干什么。否则出现请求失败时你可能分不清是 Claude Code 配置错了还是兼容服务层没启动还是本地模型没有加载成功。4.5 模型识别错误不是模型名不存在而是版本名单不匹配模型识别错误在接入第三方模型时非常常见。这里要区分三种情况现象常见原因处理方向请求发出后返回模型不存在下游模型服务没有该模型 ID在兼容服务层确认模型名称请求还没发出CLI 启动阶段就拒绝Claude Code 内置模型名单不识别升级 CLI 或做模型名映射请求能发出但工具调用失败模型不支持 Claude Code 要求的工具格式换用支持工具调用的模型或关闭需要工具调用功能很多人在第一类情况里直接修改代码硬编码模型名结果越改越乱。正确顺序是先确认是哪一层不识别再决定在哪一层修改。5. 运行验证从最小对话到实际任务5.1 最小冒烟测试环境配置完成后不要一上来就处理大型项目。先在空目录里做一个最小测试确认链路通了再说。进入一个临时目录mkdir claude-test cd claude-test claude在交互界面里输入请创建一个 hello.py 文件内容是一段读取命令行参数的 Python 脚本然后运行它验证输出。正常情况下Claude Code 会列出计划请求执行写文件命令再请求执行运行命令。你需要观察每一步是否需要确认以及最终是否生成代码。如果这一步成功说明 API Key、网络、模型参数、工具调用链路都是通的。5.2 在 VS Code 中配置 Claude CodeVS Code 扩展提供了图形化入口。安装官方扩展后需要确保系统里已经安装了 Claude Code CLI。打开任意项目在侧边栏启动会话。VS Code 扩展的优势是能看到文件树和差异视图。模型修改文件后你可以在编辑器里直接审查变更。这里比终端交互更适合做代码审查因为改动块高亮比纯文本输出更直观。配置时重点确认以下选项工作区权限是否允许模型读取全部文件。命令执行权限是否允许模型运行终端命令。自动接受模式是否开启后不再逐条确认。在个人本地环境可以放宽权限但在共享项目或生产环境里建议保持逐条确认避免模型误操作覆盖重要文件。5.3 观察请求走向与日志如果接入的是第三方或本地兼容服务层你需要确认请求真的发到了你期望的端点而不是回退到官方 API。可以使用调试模式运行claude --verbose或者claude --debug不同版本的日志开关名可能不同--verbose通常已经能输出关键步骤。日志中应能观察到请求目标地址、模型名称和基本耗时。如果看到地址仍然是官方 API说明环境变量没有在当前进程生效或者 shell 配置没有被重新加载。验证原则不要只看能不能输出文字要观察请求去往哪个端点、用了哪个模型、实际耗时是多少。只有这三个数据都对才算真正配置成功。6. 常见故障排查从现象倒推原因6.1 命令无法识别现象claude 不是内部或外部命令或无法将“claude”项识别为 cmdlet排查顺序如下检查是否安装成功npm list -g --depth0。找到全局目录npm prefix -g。把对应的 bin 目录加入 PATH。重新打开终端再执行claude --version。Windows 用户还要检查 PowerShell 执行策略。如果执行脚本被禁止官方文档通常会提供调整方法。这个问题的预防手段是在安装前就确认 npm 全局 bin 目录已经在 PATH 中。6.2 连不上 api.anthropic.com现象unable to connect to anthropic services failed to connect to api.anthropic.com这是网络层连接失败不是模型层报错。可能原因包括 DNS 解析异常、网络出口不通、TLS 被中间设备拦截、防火墙阻断。先做基础检查curl -I https://api.anthropic.com nslookup api.anthropic.comcurl能返回 HTTP 状态码说明网络通路正常如果超时说明出口被限制。nslookup能解析出域名说明 DNS 没问题如果解析失败先处理 DNS。这类问题不要反复重启 CLI要优先确认网络层。网络恢复后再尝试运行一次最小对话。注意不要把网络连接问题和账号权限问题混在一起。连接错误通常发生在请求到达服务端之前此时修复 API Key 没有意义。先确认网络层再确认鉴权层最后确认模型层。6.3 新用户不可用提示现象unfortunately, claude is not available to new users right now这个提示意味着当前账号或当前访问方式没有获得使用资格可能是订阅类型、账户状态或服务开放范围限制。解决方向是确认使用的是 API Key而不是网页端免费额度。检查账户是否绑定了有效的付费方案。查阅 Anthropic 官方文档确认当前账号所在的可用范围。联系官方支持而不是寻找非官方绕过方式。这个问题的核心是账号资格而不是技术配置。继续调整环境变量不会有效果。6.4 模型不识别现象deepseek-v4-pro is not a model this version of claude code recognizes原因和解决办法在 4.5 中已经说明。这里补充一个排查顺序先看报错发生在 CLI 启动阶段还是请求发出之后。启动阶段报错优先升级 CLI 或检查模型名映射。请求发出后报错优先检查下游模型服务实际可用模型列表。不要为了绕过这个检查而修改 CLI 内部文件。那样会导致版本升级时配置失效还会让问题更难排查。6.5 API Key 和认证错误认证类错误通常返回 401 或 403。常见原因错误现象常见原因处理建议401 UnauthorizedAPI Key 不存在、过期或格式错误重新创建 Key并确认环境变量已加载403 Forbidden账号没有该模型或接口的访问权限检查账户套餐和模型权限429 Too Many Requests请求超过限流额度降低并发等待重试窗口排查时先确认环境变量里是否有值echo $ANTHROPIC_API_KEY如果输出为空说明环境变量没有设置成功。6.6 完整排查顺序表当工具整体不可用时按下面顺序排查最快步骤检查内容验证方式1命令是否存在claude --version2环境变量是否加载echo $ANTHROPIC_API_KEY