被环境配置劝退？Claude Code 从安装到API对接保姆级教程（macOS适用）

前言最近AI工具更新太快很多朋友想试试Claude Code却被环境配置卡住——不是缺Node.js就是海外API调用麻烦教程看了一堆还是跑不通。作为踩过坑的开发者我明白这种“明明很简单的工具却卡在第一步”的挫败感。这篇文章就是为解决这些问题而来从Node.js安装到Claude Code配置再到国内API直连全程实操步骤关键命令尽量帮你少走弯路。我会用最直接的方式带你走通每一步确保一步步跟着就能完全复现。正文一、准备工作安装 Node.jsClaude Code 要求 Node.js 版本 ≥18建议用LTS稳定版先确保环境满足。方法一官网下载适合不熟悉命令行的用户访问 Node.js官网下载 macOS 的 LTS 版本双击安装包后按向导完成安装即可。方法二Homebrew 安装推荐命令行更高效如果你常用终端直接用 Homebrew 安装brewinstallnode验证安装是否成功安装完成后打开终端输入以下命令能显示版本号说明安装成功node--version# 输出 v18.x.x 或更高npm--version# 输出对应的 npm 版本二、安装 Claude CodeNode.js 准备好后用 npm 全局安装 Claude Codenpminstall-ganthropic-ai/claude-code验证安装是否成功安装完成后输入以下命令检查版本claude--version能显示版本号如0.1.0说明安装成功。三、配置 API 连接核心步骤Claude Code 需要 API 密钥才能使用这里以国内直连方案为例省去海外账户和翻墙步骤。1. 获取 API Key我这次使用的是 88api 作为中转接口https://api.88api.shop主要是为了省去海外账户注册和网络配置的麻烦国内可直连且支持多模型统一管理。大家用自己的也可以。这里以我使用的api为例获取 Key 的步骤如下注册后进入控制台点击侧边栏“API 令牌”点击“添加令牌”根据需要选择分组Claude 模型建议选“claude code”分组选择分组根据需要调用的模型选择分组a. claude 模型建议使用 calude code 分组、b. gpt 模型建议使用 codex分组可通过平台的模型广场查看不同模型支持的分组若在使用中出现上游分组饱和请切换分组使用提交后点击“复制”按钮保存生成的 API 令牌即 API Key2. 配置 API推荐用配置文件通过配置文件统一管理参数比环境变量更方便后续修改。配置文件路径~/.claude/settings.json配置内容{env:{ANTHROPIC_AUTH_TOKEN:你的API密钥,// 替换为刚复制的 KeyANTHROPIC_BASE_URL:https://api.88api.shop// 中转接口地址}}创建步骤打开终端依次输入以下命令# 创建 .claude 目录如果已存在会自动跳过mkdir-p~/.claude# 用 nano 编辑配置文件nano~/.claude/settings.json粘贴上述配置内容按CtrlO保存CtrlX退出编辑器。3. 备选方案环境变量配置临时或永久如果不想用配置文件也可以通过环境变量设置临时生效仅当前终端exportANTHROPIC_BASE_URLhttps://api.88api.shopexportANTHROPIC_AUTH_TOKEN你的API密钥# 替换为实际 Key永久生效所有终端将以下内容写入 shell 配置文件如~/.zshrc或~/.bashrcexportANTHROPIC_BASE_URLhttps://api.88api.shopexportANTHROPIC_AUTH_TOKEN你的API密钥# 替换为实际 Key保存后执行source ~/.zshrc或对应配置文件使其生效。⚠️注意务必将你的API密钥替换为实际复制的 Key否则无法连接。配置后需重启终端如果在 VS Code/Cursor 等 IDE 中使用需重启整个 IDE仅重启终端可能不生效。4. VSCode 插件配置可选如果使用 VSCode 的 Claude 插件需额外创建插件专用配置文件配置文件路径~/.claude/config.json配置内容{primaryApiKey:any}创建步骤# 创建目录如已存在跳过mkdir-p~/.claude# 编辑配置文件nano~/.claude/config.json粘贴内容后保存退出即可。⚠️注意这是插件专用的config.json与命令行工具的settings.json是两个文件不要混淆。四、开始使用 Claude Code配置完成后在终端输入以下命令启动claude首次启动可能需要确认协议按提示操作即可。如果想查看命令说明输入claude --help。五、常见问题排查问题 1启动后提示“Unable to connect to Anthropic services”症状启动 Claude Code 后报错无法连接服务。原因首次启动引导流程未完成。解决方案手动创建引导完成标记文件配置文件路径~/.claude.json配置内容{hasCompletedOnboarding:true}创建方法终端输入以下命令一键创建cat~/.claude.jsonEOF { hasCompletedOnboarding: true } EOF创建后验证文件是否存在cat~/.claude.json# 输出上述 JSON 内容即成功重启 Claude Code 即可解决。调试小技巧如果仍无法连接先检查网络、重启终端/IDE再确认 API Key 和ANTHROPIC_BASE_URL是否配置正确参考步骤三。总结这篇教程从 Node.js 安装到 Claude Code 配置再到国内 API 直连覆盖了 macOS 环境下的完整流程。核心解决了“海外账户麻烦”“环境配置复杂”“启动报错”三个常见问题所有命令和配置都经过实测按步骤操作基本能一次跑通。如果遇到其他问题欢迎在评论区留言我会尽量回复。工具的价值在于用起来希望这篇文章能帮你少折腾环境多专注于实际使用。