macOS 上安装 Claude Code + 配置 CodeGateway 完整教程

macOS 安装 Claude Code + 配置 CodeGateway 完整指南

TL;DR：macOS 是运行 Claude Code 最顺畅的平台之一。安装路线两条：通过 Homebrew 安装 Node.js 再装 Claude Code，或直接用 npm 安装。安装完后把 API 端点换成 CodeGateway，就能告别连接超时和 unsupported region 报错，稳定使用全套 Claude 模型。整个流程 10–15 分钟。

前置条件

第一步：安装 Node.js

Claude Code 是 Node.js CLI 工具，先装 Node.js。macOS 上有三种方式，推荐按顺序优先选择：

方法一：Homebrew（最推荐）

如果你还没有 Homebrew，先安装：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后（Apple Silicon Mac 需要额外执行 eval "$(/opt/homebrew/bin/brew shellenv)" 并加入 .zshrc），安装 Node.js：

brew install node

验证：

node --version   # 应输出 v22.x.x 或更高
npm --version    # 应输出 10.x.x 或更高

方法二：nvm（多版本管理）

如果你需要在多个 Node.js 版本间切换（比如同时跑其他项目）：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重载 shell
source ~/.zshrc   # 或 source ~/.bashrc（看你用哪个 shell）

# 安装 LTS 版本
nvm install --lts
nvm use --lts

方法三：官网下载安装包

访问 nodejs.org，下载 macOS 安装包（.pkg），双击安装。简单但不便于日后版本管理。

第二步：安装 Claude Code

Node.js 就绪后，在终端执行：

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

验证安装：

claude --version

预期输出：

@anthropic-ai/claude-code/1.x.x darwin-arm64 node-v22.x.x

（Intel Mac 显示 darwin-x64，Apple Silicon 显示 darwin-arm64）

实测说明：我们在 M2 MacBook Air（macOS 14.5）上实测，npm install -g @anthropic-ai/claude-code 全程约 45 秒，无需任何额外编译步骤，Apple Silicon 原生支持，不走 Rosetta 2。

处理权限问题

如果安装时提示 EACCES: permission denied：

# 检查 npm 全局目录
npm config get prefix

# 如果是 /usr/local，建议改到用户目录
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# 添加到 PATH（zsh 用户）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 重新安装
npm install -g @anthropic-ai/claude-code

第三步：注册 CodeGateway 获取 API Key

1. 访问 codegateway.dev，注册账号

2. 注册后自动获得 $2 免费额度（无需绑卡，直接可用）

3. 进入控制台 → API Keys → Create New Key

4. 复制生成的 key（格式：cgw-xxxxxxxxxx）

这个 key 只显示一次，请立即复制并妥善保存。

关于充值：pay-as-you-go，无订阅费，充值 $5 起，最高 $10,000，任意整数。按 token 计费，markup 1.35×，用量越大倍率越低。

第四步：配置 Claude Code 使用 CodeGateway

Claude Code 通过以下两个环境变量控制 API 连接：

• ANTHROPIC_API_KEY — 你的 API key

• ANTHROPIC_BASE_URL — API 端点地址

永久配置（推荐）

macOS 默认使用 zsh，编辑 ~/.zshrc：

# 打开配置文件
open -a TextEdit ~/.zshrc
# 或用命令行编辑器
nano ~/.zshrc

在文件末尾添加：

# CodeGateway 配置
export ANTHROPIC_API_KEY="cgw-你的key"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"

保存后重新加载：

source ~/.zshrc

如果你用 bash（较老的 macOS 或手动改了默认 shell），改成 ~/.bash_profile 或 ~/.bashrc。

临时配置（仅当前终端窗口有效）

export ANTHROPIC_API_KEY="cgw-你的key"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"
claude

项目级 .env 配置

在项目根目录创建 .env 文件：

cat > .env << 'EOF'
ANTHROPIC_API_KEY=cgw-你的key
ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1
EOF

Claude Code 会自动读取当前目录的 .env 文件。

第五步：验证配置

在任意目录运行：

claude

看到 Claude Code 的交互界面后，输入一条简单指令：

> 帮我写一个 Python 单行 hello world

如果正常收到回复，配置成功。

确认环境变量已生效：

echo $ANTHROPIC_BASE_URL
# 预期：https://api.codegateway.dev/v1

echo ${ANTHROPIC_API_KEY:0:6}
# 预期：cgw-xx（只显示前 6 位，避免 key 泄漏）

常见问题排错

Q: 安装 Homebrew 时提示需要 Xcode Command Line Tools

A: 这是正常的，Homebrew 依赖 git 和其他工具。按提示执行：

xcode-select --install

弹出安装窗口后点同意，等待几分钟。

Q: Apple Silicon (M1/M2/M3) 上安装 Homebrew 后 brew 命令找不到

A: Apple Silicon 下 Homebrew 安装在 /opt/homebrew/，需要将它加入 PATH：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

Q: 运行 claude 后一直等待，没有响应

A: 最可能的原因是 ANTHROPIC_BASE_URL 未设置或设置了官方端点。检查：

echo $ANTHROPIC_BASE_URL

如果输出为空，说明环境变量没加载。执行 source ~/.zshrc 后重试。

Q: 提示 unsupported region 后立即退出

A: 这是连接到官方 API endpoint 时的区域限制。确保 ANTHROPIC_BASE_URL 已正确设置为 https://api.codegateway.dev/v1，CodeGateway 路由到没有区域限制的节点。

Q: 终端关了重开后配置就失效了

A: 说明你是用 export 临时设置的，而不是写进 ~/.zshrc。按第四步"永久配置"操作，把两行 export 加进 ~/.zshrc。

Q: 我有多台 Mac，怎么同步配置？

A: 把 .zshrc 的配置段加入你的 dotfiles 仓库（比如放在 GitHub 私有仓库），或用 Mackup 等工具同步。不要把 `ANTHROPIC_API_KEY` 提交到公开仓库。

常见报错完整对照表

进阶技巧

在多个项目中使用不同 Key

如果你的团队成员有各自的 CodeGateway 账号，可以用 .env 文件做项目级隔离：

# 项目 A：个人账号
echo 'ANTHROPIC_API_KEY=cgw-individual-key' > ~/projects/projectA/.env

# 项目 B：团队账号
echo 'ANTHROPIC_API_KEY=cgw-team-key' > ~/projects/projectB/.env

进入哪个项目目录，Claude Code 自动用那个项目的 key。

在 VS Code 中集成 Claude Code

Claude Code 与 VS Code 配合使用效果最佳。在项目目录打开 VS Code，然后在 VS Code 内置终端启动 Claude Code：

# 进入项目目录
cd ~/projects/my-project

# 用 VS Code 打开
code .

# 在 VS Code 终端里运行
claude

这样你可以在左侧看文件树，左边编辑代码，右边终端里与 Claude Code 对话〔—全在一个窗口内完成。

常用 Claude Code 工作流程

Claude Code 不仅仅是一个聊天机器人，它能直接操作文件系统。一些常用场景：

# 在项目目录运行后，可以用自然语言指令 Claude Code

# 让它解释一段代码
> 解释一下 src/api/handler.py 里的 rate_limit 函数是怎么工作的

# 让它直接修改文件
> 把 handler.py 里的日志格式改成 JSON structured logging

# 电通起脚架
> 帮我起一个 Express.js + TypeScript 的项目结构

CodeGateway 支持的模型

CodeGateway 支持全套 Claude 模型以及 OpenAI 系列，主要包括：

• Claude Opus系列（最强推理能力，适合复杂项目）

• Claude Sonnet系列（速度与质量平衡，日常开发首选）

• Claude Haiku系列（最快最便宜，适合简单质疑）

• GPT-4o / GPT-4o mini 等 OpenAI 模型

Claude Code 默认使用 claude-opus 处理复杂任务，首次使用 $2 免费额度就能跟它深入交流一个硬範项目了。

让开发体验更顺滑

配置 Claude Code 项目记忆（CLAUDE.md）

Claude Code 支持在项目根目录放一个 CLAUDE.md 文件，里面写项目背景、技术栈说明、代码风格要求。每次启动时 Claude Code 会自动读取，不需要重复说明背景：

cat > CLAUDE.md << EOF
# 项目背景
这是一个 Next.js 14 + TypeScript 项目，使用 Tailwind CSS 和 Prisma ORM。

# 代码风格
- 使用函数式组件，不用 class component
- 所有异步操作必须有 try/catch 错误处理
- 变量命名用 camelCase，组件用 PascalCase

# 注意事项
- 数据库操作走 /lib/db.ts 封装层，不要直接用 prisma client
- 环境变量必须在 .env.example 里有对应注释
EOF

这个文件提交到 git，团队所有人用 Claude Code 时都能共享同一套上下文。

设置 CodeGateway 用量提醒

在 CodeGateway Dashboard 里可以设置余额低于某个阈值时发邮件提醒，避免账户余额耗尽导致 Claude Code 中断。建议设置在 $2–$5 的提醒阈值，提前充值。

使用 claude --continue 恢复上下文

Claude Code 支持继续上次的对话：

# 继续最近一次会话
claude --continue

# 查看历史会话列表
claude --history

适合跨天继续同一个任务，不需要重新描述背景。

团队协作场景：多人共用 CodeGateway

如果你是团队负责人，可以给每个团队成员生成独立的 API Key，在 CodeGateway Dashboard 里分别追踪用量。每把 Key 独立计费，方便核算各自消耗。

推荐做法：在项目的 .env.example 里预留 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL 字段，注释说明从 CodeGateway Dashboard 获取，避免有人误用官方 API Key 导致连接问题。

# .env.example
# 从 https://dashboard.codegateway.dev 获取你的 API Key
ANTHROPIC_API_KEY=cgw-your-key-here
ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1

这样新成员加入项目、拿到 .env.example 就知道怎么配置，不需要额外说明。

💡 小提示：CodeGateway 的计费是实时的，每次 API 调用完成后立即扣费，Dashboard 余额实时刷新。你可以在任意时间充值，不需要预先买套餐，也没有订阅费。$2 免费额度用完后，$5 起充即可继续，按实际用量付费，用多少花多少。

多模型配置：按任务选模型省钱

CodeGateway 支持 Claude 全系，通过环境变量或 /model 命令切换：

# ~/.zshrc 里可以设置别名快速切换
alias cg-haiku='CLAUDE_MODEL=claude-haiku-4-5 claude'
alias cg-sonnet='CLAUDE_MODEL=claude-sonnet-4-6 claude'
alias cg-opus='CLAUDE_MODEL=claude-opus-4-7 claude'

成本参考（按 CodeGateway 1.35× markup）：

用量越高，CodeGateway 的阶梯倍率越低，详见 阶梯倍率详解。

实战场景：在 macOS 上用 Claude Code 高效开发

场景一：Terminal + Claude Code 组合键盘流

macOS 的 Terminal.app 或 iTerm2 配合 Claude Code，一套键盘流就能完成大多数开发任务：

# 在项目目录启动 Claude Code
cd ~/projects/my-app
claude

# 常用指令示例
> 帮我写这个 TypeScript 接口的单元测试，用 Jest
> 找出这个文件里所有没有错误处理的 async 函数
> 把这段代码重构成更符合 SOLID 原则的写法

实测体验：在 M2 MacBook Pro 上，Claude Code 响应通常在 2–5 秒内返回（取决于任务复杂度），通过 CodeGateway 的 Cloudflare 边缘节点，延迟比直连官方 API 稳定。

场景二：Homebrew 包管理 + Claude Code 协同

Claude Code 能直接帮你查文档、写 Homebrew 脚本：

# 让 Claude Code 帮你检查 Brewfile
brew bundle dump --file=Brewfile
claude
> 分析这个 Brewfile，找出可能互相冲突的包，并给出优化建议

场景三：Xcode 项目辅助

如果你做 iOS/macOS 开发，Claude Code 可以配合 Xcode 项目：

cd ~/projects/MyiOSApp
claude
> 帮我检查 AppDelegate.swift 里的内存管理问题
> 把这个 Objective-C 方法翻译成 Swift 6 并发安全的版本

场景四：Shell 脚本自动化

macOS 日常自动化任务：

claude
> 帮我写一个 shell 脚本：每天早上 9 点自动把 ~/Downloads 里超过 30 天的文件移到 ~/Archive
> 用 osascript 写一个 macOS 通知，在 git push 成功后弹出提示

小结

macOS 是 Claude Code 的一等公民平台，原生 Unix 环境让整个流程比 Windows 少了 WSL2 这一层。如果之前遇到过连接超时或 unsupported region，改到 CodeGateway 后实测延迟约 150–300ms，稳定性和官方端点一致。

相关阅读

• Claude Code 完整配置指南：从环境准备到 Skills 实战

• Claude Code 连接超时排查：5 分钟稳定接入

• Claude Code 进阶技巧：子代理、MCP、成本优化

• 充值 & 费用指南