macOS 安装 Claude‑Code 完整踩坑指南（2026）

简介

Claude‑Code 是 Anthropic 推出的终端AI编程Agent，可以直接在终端读取项目代码、写代码、执行命令、处理Git工作流。 国内用户最大痛点：浏览器可以访问 Claude 网页，但是终端CLI会被Cloudflare地区拦截，出现403、地区不可用报错。

⚠️重要区分两件事：

1. 安装客户端本体：只是一个本地命令行程序，理论可以装成功。

2. 调用Anthropic官方API：受地区风控，国内网络环境很难稳定跑通。

系统要求

• macOS ≥13.0+

• Apple Silicon(M系列) / Intel 均可

• 推荐内存 ≥8GB

一、三种安装方式（我使用的是方式2）

方式1：官方一键脚本（国内大概率失败，不优先推荐）

官方文档推荐命令，国内网络经常返回HTML错误页面，不要加sudo！

# 不要带sudo
curl -fsSL https://claude.ai/install.sh | bash

报错：bash: line 1: syntax error near unexpected token '<' 含义：curl没有拿到shell脚本，下载到了App unavailable in region的HTML网页，直接放弃该方案。

方式2：Homebrew安装（Mac国内用户首选）

绕开claude.ai脚本下载接口，使用brew cask安装二进制包。

# 如果需要代理再执行这两行，不需要可以跳过
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

brew install --cask claude-code

方式3：手动下载二进制包（brew也被拦截时兜底）

1. 浏览器打开 release页面：https://github.com/anthropics/claude-code/releases

2. M系列Mac下载：claude-code‑darwin‑arm64.tar.gz

3. Intel Mac下载：claude-code‑darwin‑x86_64.tar.gz

# 创建bin目录
mkdir -p ~/.local/bin
# 解压（修改为你实际下载的文件名）
tar -zxvf ~/Downloads/claude-code-darwin-arm64.tar.gz -C ~/.local/bin

# 加入PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 解除mac隔离拦截
xattr -cr ~/.local/bin/claude

✅验证是否安装成功

claude --version

输出版本号，例如 2.1.236 (Claude Code)，代表客户端本体安装完成。

二、网络代理环境变量核心知识点（高频踩坑）

很多人疑惑：浏览器可以Google，为什么终端不行？

浏览器代理 ≠ 终端代理，两者完全隔离。浏览器内部配置的代理不会自动给curl/claude命令使用。

# 设置终端HTTP代理，仅对**当前终端窗口临时生效**
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

• HTTP_PROXY：处理http请求

• HTTPS_PROXY：处理https加密请求（绝大多数网站）

重要坑点

1. 新开终端窗口，环境变量全部丢失，需要重新export。

2. sudo执行命令，默认不会继承普通用户的代理环境变量，不要随便sudo curl | bash，极易出错。

3. CC‑Switch使用国内模型时，必须清除代理变量，否则国内API会走海外代理，超时报错。

清除代理命令：

unset HTTP_PROXY
unset HTTPS_PROXY

永久写入zshrc（仅访问官方Anthropic时使用）

cat >> ~/.zshrc <<'EOF'
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
EOF
source ~/.zshrc

测试代理是否生效：

curl -I https://claude.ai/install.sh

三、两种运行模式

模式A：访问Anthropic官方接口（海外网络）

即使设置代理，机房代理IP大概率被Cloudflare返回403。住宅IP成功率更高。

1. 设置终端代理

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

2. 启动

claude

3. 交互终端执行登录

/login

复制输出链接，在带代理浏览器打开，完成OAuth授权登录。

典型报错

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: Status 403

含义：IP被Cloudflare风控拦截，Node.js客户端无法完成浏览器人机验证，换IP或者切换模式B。

模式B：CC‑Switch切换国产兼容API（国内兜底方案，推荐）

Claude‑Code只是一个通用Agent外壳，支持兼容Anthropic协议的第三方API。 CC‑Switch是社区开源GUI工具，自动改写Claude‑Code配置，跳过官方登录校验，直接调用国内大模型（DeepSeek‑Coder、智谱GLM‑4‑Code、MiniMax等），不需要访问api.anthropic.com，不需要海外网络。

安装CC‑Switch

方式1 brew安装

brew tap farion1231/ccswitch
brew install --cask cc-switch

方式2 手动下载dmg https://github.com/farion1231/cc‑switch/releases/tag/v3.10.1 下载 CC‑Switch‑v3.10.1‑macOS.dmg，拖入应用程序。

Mac打开提示「无法验证开发者」：右键App → 打开；系统设置 → 隐私与安全性，点击「仍要打开」。

CC‑Switch配置步骤

1. 打开CC‑Switch，切换到Claude标签页；

2. 右上角+，添加供应商，选择预设模型；

3. 填入你在对应平台申请的API‑Key；

4. 添加后点击【启用】，状态变为使用中。

CC‑Switch自动修改两个配置文件：

• ~/.claude.json：hasCompletedOnboarding: true，跳过官方登录引导

• ~/.claude/settings.json：写入ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN环境配置

测试使用

⚠️新开终端窗口，务必清除代理变量！

unset HTTP_PROXY
unset HTTPS_PROXY

claude

进入交互终端，直接使用全部Agent能力，读写本地文件、执行命令。

简单测试指令：

写一个python hello world脚本保存到hello.py

手动配置备选（不安装CC‑Switch）

~/.claude.json

{
  "hasCompletedOnboarding": true
}

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "兼容接口地址",
    "ANTHROPIC_AUTH_TOKEN": "你的API‑Key"
  }
}

四、常见报错速查表

五、重要文件路径

1. Claude‑Code配置目录：~/.claude/

2. 配置文件：~/.claude/settings.json

3. 跳过登录配置：~/.claude.json

4. 二进制手动安装目录：~/.local/bin/claude

六、卸载命令

# brew安装卸载
brew uninstall --cask claude-code

# 清理配置文件
rm -rf ~/.claude
rm -rf ~/.claude.json

声明：CC‑Switch属于社区第三方开源工具，请自行评估代码安全风险。

另外，可以在vscode中安装claude code插件，然后使用：