Claude Code 配置实战：从安装、环境变量到第三方 API 接入的完整踩坑记录

最近社区里讨论 Claude Code、Codex 的帖子越来越多，我自己在三个系统上反复装了几遍、踩了不少坑，干脆按"做项目写总结文档"的习惯，把这条路完整记录下来。命令都实测过，但官方更新很快，具体以官方文档为准；涉及第三方服务仅作客观记录，不构成推荐。

一、先想清三个问题，再动手

按我自己和身边同学的经验，配 Claude Code 失败大多不是命令打错，而是没先想清三件事：

1. 安装方式：官方原生安装，还是 npm？
2. API 来源：Anthropic 官方，还是第三方 Anthropic 兼容接口？
3. 配置位置：临时变量、shell 永久变量，还是 .claude/settings.json？

这三点理顺，后面都是顺水推舟。结论先放这儿：

• 新手 / 没装过 Node → 官方原生安装；有 Node.js 18+ → npm 也行，且只保留一种安装来源；
• API 先用临时变量跑通，再固化为永久配置；
• 第三方 → 务必确认是 Anthropic 兼容，而非 OpenAI 兼容。

这里多说一句方法论：跟着任何教程做的时候，多问自己"为什么这么配？有没有更优解？"。下面每一步我都标了踩坑点，建议你边做边记笔记。

二、Claude Code 是什么，适合谁

Claude Code 是 Anthropic 推出的、偏终端形态的 AI 编码助手。和普通对话式 AI 的区别在于：它能驻留在项目目录里读文件、理解结构、给修改建议，授权后还能执行命令。

做项目时我常用它：读 README 快速理解项目、梳理目录结构、顺着报错定位可疑文件、生成 / 改写函数与测试、解释 Git diff、在终端完成跨文件任务。

选型一句话：只改一小段代码，VS Code 插件更顺手；想让它吃透整个项目、配合命令行干活，CLI 版更适合作为主入口。

三、安装前：别默认"必须先装 Node"

老教程多从 npm 起步，开口就让装 Node。现在这个前提已松动：

• 官方原生安装不一定要 Node；
• 只有选 npm 才需要 Node.js 18+；
• 装过旧版的，先确认机器里有几个 claude 来源。

走 npm 先看版本：

▼
bash
复制代码
node -v
npm -v

确认当前版本：

▼
bash
复制代码
claude --version

这一步常被忽略，恰是版本冲突的根源——查它来自哪个路径：

▼
bash
复制代码
which -a claude   # macOS / Linux，列出所有来源

▼
powershell
复制代码
where claude      # Windows

which -a 列出两条以上，基本可确认多来源冲突，留一个、删其余。

四、安装实操（原生 / npm 两条线）

4.1 官方原生安装（推荐新手）

Windows（PowerShell）常见形式：

▼
powershell
复制代码
irm https://claude.ai/install.ps1 | iex

CMD 用户别直接粘 PowerShell 这行，语法不通用，查官方文档的 CMD 写法。

macOS / Linux：

▼
bash
复制代码
curl -fsSL https://claude.ai/install.sh | bash

macOS 想用 Homebrew、Linux 想用 apt/dnf/apk 的，看官方当前是否支持，包名偶尔会变。

4.2 npm 安装（已有 Node 18+）

▼
bash
复制代码
npm install -g @anthropic-ai/claude-code

国内拉官方源慢，可换镜像：

▼
bash
复制代码
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
claude --version

镜像偶有版本滞后，装完务必 --version 核对。

4.3 验证安装

▼
bash
复制代码
claude --version
claude --help

能看到 Claude Code v2.x.x 这类版本号 + 帮助信息即可，别纠结具体版本号。

高频坑：Windows 下 PowerShell 的 && 可能报错（拆多行）；命令不存在多是 PATH 没生效（改完重开终端）；Linux 服务器很多"装失败"其实是 SSH 的 shell 没读到路径，查 .bashrc / .profile / .zshrc。

五、环境变量详解

API 接入的核心就是这几个变量：

最易踩点：ANTHROPIC_API_KEY 与 ANTHROPIC_AUTH_TOKEN 不能随便选——有的服务商认前者，有的认后者，必须看其文档，别凭感觉填。

5.1 临时变量（首测用）

macOS / Linux：

▼
bash
复制代码
export ANTHROPIC_BASE_URL="https://你的服务商/anthropic-compatible-endpoint"
export ANTHROPIC_AUTH_TOKEN="你的 API Key"
export ANTHROPIC_MODEL="你的模型名"
export API_TIMEOUT_MS="300000"

Windows PowerShell：

▼
powershell
复制代码
$env:ANTHROPIC_BASE_URL="https://你的服务商/anthropic-compatible-endpoint"
$env:ANTHROPIC_AUTH_TOKEN="你的 API Key"
$env:ANTHROPIC_MODEL="你的模型名"
$env:API_TIMEOUT_MS="300000"

临时变量只对当前窗口有效，关掉即失效，适合首测。

5.2 永久配置（二选一，别两边都写）

写进 shell（macOS 默认 zsh 进 ~/.zshrc，Linux bash 进 ~/.bashrc）后：

▼
bash
复制代码
source ~/.zshrc   # 或 source ~/.bashrc

或集中写进 .claude/settings.json：

▼
json
复制代码
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的 API Key",
    "ANTHROPIC_BASE_URL": "https://你的服务商/anthropic-compatible-endpoint",
    "ANTHROPIC_MODEL": "你的模型名",
    "API_TIMEOUT_MS": "300000"
  }
}

踩过的坑：JSON 别留多余逗号；Key 别提交公开仓库；改完重启终端 / 应用；系统变量与配置文件重复定义同一变量时，谁优先受版本和启动方式影响，排错前先删重复项。

5.3 验证变量是否生效

▼
bash
复制代码
echo $ANTHROPIC_BASE_URL    # macOS / Linux

▼
powershell
复制代码
echo $env:ANTHROPIC_BASE_URL  # Windows

输出为空就别急着调 API——此时 API 怎么改都没用，先解决变量来源。

六、API 接入：官方与第三方兼容

6.1 接官方 Anthropic API

用官方一般不用配 ANTHROPIC_BASE_URL，配好官方 Key 即可：

▼
bash
复制代码
export ANTHROPIC_API_KEY="你的 Anthropic API Key"

兼容风险最低，但访问条件、计费、地区和模型开放以官方最新说明为准。

6.2 接第三方 Anthropic 兼容 API（最容易卡的一步）

最关键的一点：确认它是 Anthropic 兼容，而非 OpenAI 兼容。Claude Code 要的不是随便一个 /v1/chat/completions，而是能兼容 Anthropic Messages API 形态的 endpoint。

接入前逐项确认：

▼
text
复制代码
[ ] 拿到的是 Anthropic 兼容地址，不是 OpenAI 兼容地址
[ ] 清楚 Base URL 要不要带 /v1
[ ] 清楚 Key 该放 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY
[ ] 知道模型名的准确写法
[ ] 确认它支持 messages 接口
[ ] 了解计费、日志、数据使用政策

国内能直连官方 API 的情况有限，所以不少人会用第三方 Anthropic 兼容服务来接 Claude Code。我测试时用过几家，其中一家是 ClaudeAPI（www.claudeapi.com），属于第三方 Claude API 兼容接入服务——它不是 Anthropic 官方。这类平台通常会提供兼容接入、多线路、中文支持、企业充值开票、基础技术协助等能力。需要强调：具体支持哪些模型、如何计费、服务条款如何，一律以其官网最新说明为准，本文仅作客观记录，请自行评估后再决定是否使用。

6.3 Base URL / Token / Model 怎么填

第三方配置参考：

▼
json
复制代码
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的 API Key",
    "ANTHROPIC_BASE_URL": "https://你的服务商/anthropic-compatible-endpoint",
    "ANTHROPIC_MODEL": "你的模型名",
    "API_TIMEOUT_MS": "300000"
  }
}

要点（与报错对应记忆，排查更快）：

• ANTHROPIC_BASE_URL 要不要 /v1 → 看文档；
• 模型名别猜，填服务商支持的精确名；
• 401 → 多半 Key 错了，或变量名用错了；
• 404 → 通常 Base URL 路径不对；
• model not found → 先查模型名拼写。

6.4 接入后验证

最小请求：

▼
bash
复制代码
claude -p "请用一句话回复：Claude Code API 已接入成功"

能返回文本，说明 CLI 已能调模型。再进真实项目验上下文：

▼
bash
复制代码
claude "阅读这个项目的 README，并总结项目结构"

第二步比第一步更说明问题——Claude Code 的价值在于"理解项目"，不只是会请求。社区里很多做项目的同学，恰恰需要它这种"读懂整个工程"的能力。

七、CLI 与 VS Code 插件怎么选

建议先把 CLI 跑通，插件后面按需加。CLI 的安装、变量、API 都好验证，终端一条命令就能定位问题；插件多一层环境，不生效时排查更绕——最典型就是你在终端临时设了变量，VS Code 没读到。

插件不生效时按序试：重启 VS Code → 改用系统级环境变量 → 改用 .claude/settings.json → 看插件自身配置说明。别默认"装了 CLI，VS Code 里就一定能用"。

八、常见报错排查表

社区里建议大家"自主解决问题"——遇到报错先抓全错误信息，再按上面这张表分类定位，大部分问题自己就能搞定。

九、安全与成本底线

• Key 不进公开仓库，不出现在截图、日志、教程里；
• 用第三方 API 前看清计费、日志、数据政策；
• 大改前先让它出计划再执行；
• 动代码前确保 Git 工作区干净，方便回滚；
• 对执行命令保持警惕，别一路确认；
• 不靠改内部配置绕登录；不用来路不明的代理脚本。

团队 / 企业场景更应往"受控"靠：统一 Key、权限分级、可审计配置。

十、小结：一条稳妥路径

1. 新手原生装；有 Node 18+ 用 npm 也行；
2. 装完先 claude --version + claude --help 验证；
3. API 先用临时变量测；
4. 跑通后写进 shell 永久变量或 .claude/settings.json（二选一）；
5. 用第三方务必确认是 Anthropic 兼容；
6. claude -p "hello" 最小请求，再进项目验上下文；
7. 出错按 401 / 403 / 404 / model not found / timeout 分类查；
8. 插件不灵先回头查变量来源；
9. Key 永远别暴露。

走完这套，你不只是把 Claude Code 装上了，而是真正理清了安装方式、环境变量、API 接入三者的关系。以后换模型、换服务商、迁新机器，排查都会轻松很多——这才是写这篇总结最值钱的地方。

以上是我个人实测整理。你在配置 Claude Code 时卡在哪一步了？是装不上、连不通，还是 401 / model not found？欢迎在评论区贴出报错一起交流。