Claude Code 安装配置指南（macOS + OneHub 中转）

工具选型与安装第 1 / 5 篇

适用环境：macOS + bash + OneHub API 中转

写作日期：2026-03-18｜复核：2026-09-07（隔将近六个月）

📌 2026-09-07 复核：结构性的部分全部仍然成立，在 Claude Code 2.1.258 上逐条实测：

本文的说法 复核结果
安装命令 curl -fsSL https://claude.ai/install.sh | bash ✅ 仍有效（301 到 downloads.claude.ai/.../bootstrap.sh）
装到 ~/.local/bin/claude ✅ 实测就是这个路径
配置写 ~/.claude/settings.json 的 env 字段 ✅ 仍是这个位置和字段名
API_TIMEOUT_MS、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC ✅ 两个变量仍被识别
~/.claude.json 的 hasCompletedOnboarding（布尔） ✅ 字段仍在，类型仍是布尔
OneHub 必须用 ANTHROPIC_API_KEY，用 ANTHROPIC_AUTH_TOKEN 报 401 ⚠️ 没法复核 —— 这条取决于 OneHub 那边的实现，手上没有可用的 OneHub key

🚨 补一条写作时没提、但会咬人的行为（在另一篇的实验里实测到）： ANTHROPIC_API_KEY 一旦设置，就会遮蔽你用 claude 登录过的官方凭据， 而且这个 key 无效时不会回退，直接硬失败在 401。 也就是说，如果你本来已经登录着官方账号，照本文配好 OneHub 之后： 所有请求都走中转；哪天那个 key 过期或欠费，你不会自动退回官方账号，只会看到 401。 ⇒ 想临时切回官方账号，把 env 里的 ANTHROPIC_API_KEY 注释掉，不是加个什么开关。

🔔 要重验就跑这四条（零成本，不需要有效 key）：

curl -sSL -o /dev/null -w '%{http_code} %{url_effective}\n' https://claude.ai/install.sh  # 期望 200
which claude                                        # 期望 ~/.local/bin/claude
claude --version                                     # 本文复核基线：2.1.258
python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude/settings.json'))); print(list(d.keys()))"
# 期望输出里有 env —— 没有的话说明配置结构变了，本文步骤三要重写

⚠️ 另外两点，属于本文一开始就没覆盖、而不是后来过期的：

  • 本文假设 shell 是 bash（标题里写了）。但 macOS 从 Catalina 起默认是 zsh， 那样步骤二要写进 ~/.zshrc 或 ~/.zprofile，而不是 ~/.bash_profile。 先跑 echo $SHELL 看自己在用哪个。
  • OneHub 是第三方中转。本文所有与它相关的结论（字段名、报错行为） 都会随那边的实现变，而那不在任何官方文档的保证范围内。

步骤一：安装 Claude Code

# 官方安装命令（或按实际安装方式）
curl -fsSL https://claude.ai/install.sh | bash

安装完成后会提示

⚠ Setup notes: • Native installation exists but ~/.local/bin is not in your PATH. Run:

echo ‘export PATH=“$HOME/.local/bin:$PATH”’ >> ~/.bashrc && source ~/.bashrc

✅ Installation complete!

步骤二：修复 PATH 环境变量

有时候安装完成后，运行时候会提示-bash: claude: command not found，可能是环境变量问题，用下面的方式补充：

macOS 的 bash 启动时读取 ~/.bash_profile，而非 ~/.bashrc，需手动将安装目录加入 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

验证是否成功：

which claude
# 预期输出：/Users/你的用户名/.local/bin/claude

⚠️ 注意：不能用 sudo echo ... >> file 写文件，因为 >> 重定向由 shell 执行，没有 sudo 权限。 如遇到权限问题，改用：

sudo tee -a ~/.bash_profile <<< 'export PATH="$HOME/.local/bin:$PATH"'

步骤三：创建 API 配置文件

这里的key就是申请后在详情里面的key，实际是OneHub的Key。

mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_API_KEY": "你的OneHub Key",
    "ANTHROPIC_BASE_URL": "https://onehub.tap4fun.com/claude",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
EOF

⚠️ 关键点：OneHub 中转 key 必须使用 ANTHROPIC_API_KEY 字段名， 使用 ANTHROPIC_AUTH_TOKEN 会报 401 无效令牌错误。

步骤四：跳过 Onboarding

这里也直接在终端复制。

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

步骤五：启动验证

完成好配置之后令其生效并启动，就可以使用了。使用前先进入你的代码文件目录，再启动claude。

source ~/.bash_profile && claude

正常启动后即可使用。

常见问题排查

问题 原因 解决方案
claude: command not found ~/.local/bin 不在 PATH 中 执行步骤二，写入 ~/.bash_profile
Permission denied 写入失败 sudo echo >> file 的重定向无权限 改用 sudo tee -a 或 sudo chown $(whoami) 文件路径
401 无效的令牌 字段名错误或 Key 无效 将字段名改为 ANTHROPIC_API_KEY，或去 OneHub 后台重新生成 Key
连接超时/重试 网络问题或 BASE_URL 配置错误 检查 ANTHROPIC_BASE_URL 是否正确

配置文件位置速查

文件 作用
~/.claude/settings.json API Key、Base URL、超时等环境变量配置
~/.claude.json 用户状态，设置 hasCompletedOnboarding: true 跳过引导
~/.bash_profile bash 环境变量，PATH 配置写在这里
.claude/settings.local.json 项目级配置（放在项目目录下）

← 返回 Agent 开发