Claude Code 安装配置教程:Mac / Linux 全流程指南

第一次装 Claude Code，卡住的地方其实不是代码能力，而是：安装命令跑不通、配置文件不知道放哪、API Key 填了还是报错。

尤其是 Mac / Linux 用户，看似只要一行命令就能安装，但真正用起来，往往还要处理模型配置、环境变量、网络状态和各种报错。

这篇就按实际使用流程来整理：从安装 Claude Code，到配置 API、启动项目、排查常见问题，尽量一步步讲清楚，适合新手直接照着操作。

unsetunset前言unsetunset

Claude Code 是一个强大的 AI 编程助手，可以让你直接在终端里和 AI 协作写代码、改代码、排查问题。

对经常写项目、调脚本、处理工程文件的人来说，它比单纯网页聊天更适合接入真实开发流程。

unsetunset📋 系统要求unsetunset

开始安装前，先确认基础环境，避免后面命令执行失败。

unsetunset🚀 安装 Claude Codeunsetunset

目前更推荐使用原生安装方式。

它的优势比较明显：

• ✅ 一个自包含的可执行文件；
• ✅ 不依赖 Node.js；
• ✅ 自动更新程序稳定性更好。

如果你之前已经安装过 Claude Code，可以使用下面这条命令迁移到原生二进制安装：

claude install

unsetunsetmacOS / Linux 系统安装步骤unsetunset

macOS、Linux、WSL 安装指令：

curl -fsSL https://claude.ai/install.sh | bash

Homebrew（macOS、Linux）安装命令：

brew install --cask claude-code

💡 提示：如果你已经安装了 Node.js 18.0 或更高版本，也可以使用 NPM 方式安装。

NPM 安装指令：

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

安装完成后，打开一个新的终端，输入下面命令验证是否安装成功：

claude --version

如果能正常显示版本号，就说明 Claude Code 已经安装好了。

unsetunset⚙️ 配置并开始使用unsetunset

接下来需要准备两个重要配置项：

✅注册入口：https://letaicode.cn/?aff=KbmuqF

然后新建或修改 settings.json 配置文件。

配置文件位置如下：

Mac: ~/.claude/settings.json 或 .claude/settings.jsonLinux: ~/.claude/settings.json

写入以下配置信息。

⚠️ 注意： 把 ANTHROPIC_AUTH_TOKEN 替换成你自己的 API 令牌，ANTHROPIC_MODEL 可以替换成你需要的其他模型 ID。

{"env": {"ANTHROPIC_AUTH_TOKEN": "sk-你的API令牌","ANTHROPIC_BASE_URL": "https://letaicode.cn/claude","ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929","ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5-20251001"  }}

PS：如果你想切换模型，直接修改 ANTHROPIC_MODEL 对应的模型名称即可。

比如想配置 opus4.7，可以把：

claude-sonnet-4-5-20250929

改成：

claude-opus-4-7

⚠️ 不过需要注意，opus 模型成本通常更高，如果预算有限，不建议长期默认使用。

Ubuntu / macOS 可以通过 vi 或 vim 命令直接创建或修改 settings.json 文件：

vim  ~/.claude/settings.json

配置完成后，在你的项目目录下输入 claude 即可启动 Claude Code：

cd /path/to/your/projectclaude

unsetunset初次运行配置unsetunset

第一次启动后，会出现一些基础配置选项，按提示选择即可。

一般流程如下：

• ✅ 选择主题 → 选择你喜欢的主题，然后按 Enter；
• ✅ 安全须知 → 确认安全须知，然后按 Enter；
• ✅ Terminal 配置 → 使用默认配置，然后按 Enter；
• ✅ 工作目录信任 → 信任当前目录，然后按 Enter。

✨ 恭喜！现在你就可以开始用 Claude Code 和 AI 一起写代码、改项目、排查问题了。

unsetunset❓ 常见问题解答unsetunset

Q: 遇到 "Invalid API Key · Please run /login" 错误？

A: 这通常说明 Claude Code 没有正确检测到环境变量。

可以重点检查这几项：

• 是否正确设置了 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL；
• 环境变量值是否填写正确，令牌一般以 sk- 开头；
• 如果使用的是永久配置，修改后是否重启了终端。

Q: 为什么显示 "offline" 状态？

A: Claude Code 会通过连接 Google 来判断网络状态。

如果显示 "offline"，不一定代表不能用，只是说明当前环境无法连接到 Google。只要 Claude Code 能正常调用模型，就不影响基础使用。

Q: 为什么浏览网页的 Fetch 会失败？

A: Claude Code 在访问网页前，需要调用 Claude 服务做安全检查。

你可以检查：

• 是否保持稳定的国际互联网连接；
• 必要时是否开启全局代理。

Q: 请求总是显示 "fetch failed"？

A: 这类问题多数和网络环境有关。

可以先尝试：

• 使用代理工具；
• 切换网络环境；
• 重启终端后重新运行 claude。

Q: API 报错如何处理？

A: 可能是转发代理不稳定导致的。

建议按下面步骤处理：

• 退出 Claude Code：Ctrl+C；
• 重新运行 claude 命令；
• 如果问题持续，可以稍后再试。

Q: 网页登录错误？

A: 可以尝试清除本站 Cookie，然后重新登录。

unsetunset🔗 相关链接unsetunset

• Claude Code 官方文档：https://docs.anthropic.com
• Node.js 官方网站：https://nodejs.org

💡 提示：如果遇到其他问题，可以优先根据报错信息逐项排查：配置文件、API Key、模型名称、网络环境，这几类问题最常见。