前言

现在很多 AI 工具的安装门槛，其实不在“有没有教程”，而在“教程能不能真的走通”。尤其是 macOS 用户，常常会在 Node.js、配置文件路径、环境变量刷新这些小地方反复卡住，最后问题并不大，但很耗时间。

这篇文章把 macOS 下 Claude Code 的安装、API 配置、可选的 VSCode 插件设置，以及常见连接报错处理整理成一套完整流程。

正文

1. 先安装 Node.js

Claude Code 要求本地先有 Node.js 环境，最低版本为 18，建议直接使用 LTS。

方法一：官网下载

访问 Node.js 官网下载 LTS 版本，双击安装包后按向导完成安装。

方法二：Homebrew 安装

如果你平时就用 Homebrew，可以直接执行：

brew install node

安装完成后先验证版本：

node --version
# 输出示例：v20.11.0

npm --version
# 输出示例：10.2.4

只要能正常返回版本号，就说明 Node.js 已安装完成。

2. 安装 Claude Code

执行下面的命令全局安装：

npm install -g @anthropic-ai/claude-code

安装后验证：

claude --version

确认命令可用后，再继续做 API 配置。

3. 配置 API 连接

3.1 获取 API Key

我最近用的是88api中转（https://api.88api.shop），使用中转站的好处就是不需要翻墙和注册海外账户，或者大家也可以用自己的。

1. 注册登录以后，点击侧边栏的 “API 令牌”

2. 点击"添加令牌"

3. 创建令牌，名称随意，直接提交

4. 获取 API Key，注意妥善保管，不要公开或分享。Base URL 是 API 服务的访问入口，后续配置时会用到，一并记录好。

5. 点击"知道了"，在令牌列表中可以点击"复制"按钮获取 API Key

这个 Key 本质上就是身份凭证，建议单独保存，避免泄露。

3.2 方法一：配置文件方式

这是更推荐的做法。

配置文件路径：

~/.claude/settings.json

配置内容：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的API密钥",
    "ANTHROPIC_BASE_URL": "你的 88API Base URL"
  }
}

创建方式如下：

# 创建 .claude 目录（如已存在则跳过）
mkdir -p ~/.claude

# 创建并编辑配置文件
nano ~/.claude/settings.json

将配置内容粘贴后保存即可。

3.3 方法二：环境变量方式

如果你不想用配置文件，也可以直接写环境变量。

临时设置当前终端：

export ANTHROPIC_BASE_URL="你的 88API Base URL"
export ANTHROPIC_AUTH_TOKEN="你的API密钥"

永久设置可写入 ~/.zshrc 或你当前使用的 shell 配置文件：

export ANTHROPIC_BASE_URL="你的 88API Base URL"
export ANTHROPIC_AUTH_TOKEN="你的API密钥"

保存后执行：

source ~/.zshrc

注意：记得把 "你的API密钥" 替换成实际生成的 Key。

如果是在 VS Code 或 Cursor 的集成终端里用 Claude Code，建议配置后彻底重启 IDE，否则新环境变量可能不会立刻生效。

4. VSCode 插件配置（可选）

如果你还在用 VSCode 的 Claude 插件，需要额外补充一个插件配置文件。

文件路径：

~/.claude/config.json

文件内容：

{
  "primaryApiKey": "any"
}

创建方式：

# 创建 .claude 目录（如已存在则跳过）
mkdir -p ~/.claude

# 创建并编辑配置文件
nano ~/.claude/config.json

这里要区分清楚，config.json 是 VSCode 插件使用的，而 settings.json 是 Claude Code 命令行工具使用的，两者作用不同。

5. 开始使用

全部配置完成后，直接启动：

claude

如果想查看命令帮助：

claude --help

6. 常见问题排查

问题 1：Unable to connect to Anthropic services

如果 Claude Code 启动后提示无法连接到 Anthropic 服务，常见原因是首次引导没有完成。处理方式是在用户根目录创建 .claude.json。

文件路径：

~/.claude.json

文件内容：

{
  "hasCompletedOnboarding": true
}

可以直接执行：

cat > ~/.claude.json << 'EOF'
{
  "hasCompletedOnboarding": true
}
EOF

再确认一下文件内容：

cat ~/.claude.json

如果内容正确，重启 Claude Code 再试即可。

调试技巧

如果问题还在，可以优先排查下面几项：

1. 网络是否正常
2. 终端或 IDE 是否已经彻底重启
3. API Key 是否填写错误
4. 配置文件路径是否写到了正确的用户目录下

总结

macOS 下安装 Claude Code 的流程并不复杂，但配置阶段的几个细节很容易让人来回折腾，比如 .claude 目录位置、环境变量加载时机，以及首次引导文件是否补齐。把这些点一次整理清楚，后面会轻松很多。

如果你只是想尽快把 Claude Code 在本机跑通，这篇里的顺序基本就够用了。后面真遇到问题，也建议优先回头检查配置路径、环境变量和重启状态，而不是先怀疑安装命令本身。