macOS/Linux 安装 Claude Code 接入中转教程

macOS 和 Linux 是 Claude Code 的「主场」，官方文档默认也是这两个平台。但真正动手时，很多人仍然会卡在几个细节上：npm 全局安装报权限错误、环境变量写进了错误的配置文件、新开终端变量又没了、明明配好了中转却还在弹官方登录。这篇把 macOS 与 Linux 上从安装到接入 Zivv 中转的完整流程走一遍，重点讲清楚环境变量持久化和 settings.json 两种配置方式，最后附上验证清单和报错对照表。Windows 用户请看 Windows 安装配置教程。

安装前准备

• macOS 较新版本，或主流 Linux 发行版（Ubuntu、Debian、Fedora 等）
• 终端可以访问安装源（npm 或官方安装脚本）
• 一把 Zivv 的 API Key：注册 后在控制台「API 令牌」页面创建，sk- 开头。重度使用 Claude Code 的话，创建 Key 时分组选「Claude MAX」

先确认自己用的是哪个 shell，后面写配置文件要用：

echo $SHELL

输出 /bin/zsh 就是 zsh（macOS 默认），输出 /bin/bash 就是 bash（多数 Linux 默认）。这一步看似多余，但「变量写进了 ~/.bashrc，实际用的是 zsh」是这类教程里最常见的失败原因。

第一步：安装 Claude Code

方式一：官方原生安装脚本（推荐）

不依赖 Node.js，一条命令完成：

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

脚本会把 claude 安装到用户目录下（通常是 ~/.local/bin），不需要 sudo。如果装完提示找不到命令，多半是 ~/.local/bin 不在 PATH 里，按下文「PATH 问题」处理即可。

macOS 用户也可以用 Homebrew 安装（cask 名为 claude-code），适合习惯用 brew 统一管理工具的人。

方式二：npm 安装

已经有 Node.js 18 及以上版本的话：

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

这里有个经典坑：不要用 sudo npm install -g。用 sudo 装出来的文件归 root 所有，后续自动更新和升级都会因为权限失败。如果不加 sudo 报 EACCES 权限错误，正确做法是把 npm 全局目录改到用户目录下：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

（bash 用户把 ~/.zshrc 换成 ~/.bashrc。）用 nvm、fnm 等版本管理器装的 Node，全局目录本来就在用户目录，一般不会遇到这个问题。

两种方式怎么选

两种方式只选一种。同时装两份会出现「升级了但版本号没变」的怪事，因为 PATH 里排在前面的那份才是你实际运行的。可以用下面命令确认：

which -a claude
claude --version

which -a 输出多行，说明装了不止一份，删掉不用的那份。

第二步：配置环境变量接入 Zivv

Claude Code 通过两个环境变量决定请求发到哪里：

• ANTHROPIC_BASE_URL=https://zivv.pro
• ANTHROPIC_AUTH_TOKEN=你的 sk- Key

两个易错点：Anthropic 协议的地址是根域名，不要加 /v1（加了会 404）；变量名是 AUTH_TOKEN，不要和其他教程里的 API_KEY 混用。

临时验证

先在当前终端临时设置，确认链路通：

export ANTHROPIC_BASE_URL=https://zivv.pro
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here
claude -p "回复 OK"

claude -p 是非交互模式，问完即退出，非常适合做连通性测试。能返回内容，说明安装和接入都没问题。

持久化：zsh

macOS 默认 zsh，把变量追加到 ~/.zshrc：

cat >> ~/.zshrc <<'EOF'
export ANTHROPIC_BASE_URL=https://zivv.pro
export ANTHROPIC_AUTH_TOKEN=sk-your-key-here
EOF
source ~/.zshrc

持久化：bash

Linux 上的 bash 稍微复杂一点：交互式非登录 shell 读 ~/.bashrc，登录 shell（比如 SSH 登录服务器）读 ~/.bash_profile 或 ~/.profile。最稳的做法是写进 ~/.bashrc，并确认 ~/.bash_profile 里有加载它的语句：

echo 'export ANTHROPIC_BASE_URL=https://zivv.pro' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN=sk-your-key-here' >> ~/.bashrc
grep -q bashrc ~/.bash_profile 2>/dev/null || echo '[ -f ~/.bashrc ] && . ~/.bashrc' >> ~/.bash_profile
source ~/.bashrc

fish 用户用 set -Ux ANTHROPIC_BASE_URL https://zivv.pro 这种通用变量写法即可。

另一种方式：settings.json 里的 env

如果你不想污染 shell 环境，或者希望配置只对 Claude Code 生效，可以写在 Claude Code 自己的配置文件里。用户级配置在 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://zivv.pro",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-key-here"
  }
}

env 字段里的变量会在每次启动 Claude Code 时注入，效果等同于环境变量，但其他程序读不到。Claude Code 的配置分几层：

一个实用组合：用户级 settings.json 放默认 Key，某个公司项目需要单独计费时，在该项目的 settings.local.json 里覆盖 ANTHROPIC_AUTH_TOKEN。settings.local.json 默认应被忽略，提交前仍建议检查一下 .gitignore。团队共享的项目级 settings.json 只放权限、模型等通用配置，不放 Key。

指定默认模型（可选）

Claude Code 内可以用 /model 随时切换模型。如果想固定默认值，可以设置 ANTHROPIC_MODEL，例如 claude-sonnet-5。模型 id 以 模型广场 或 GET /v1/models 返回为准，填错会得到 404，排查见 模型不存在 404 修复。

第三步：验证配置

新开一个终端窗口（确保读到的是持久化后的配置），按顺序执行：

1. echo $ANTHROPIC_BASE_URL 输出 https://zivv.pro（用 settings.json 方式的跳过这步）
2. claude --version 有版本号输出
3. claude -p "回复 OK" 正常返回
4. 进入任意项目目录运行 claude，输入 /status，确认显示的 API 地址是 zivv.pro
5. 到 Zivv 控制台用量页，确认能看到刚才的请求记录

第 5 步最关键：能在控制台看到用量，才能证明流量真的走了 Zivv。如果之前用官方账号登录过，建议先在 Claude Code 里执行 /logout 退出官方登录，避免两种凭证混用带来的困惑。也可以运行 claude doctor 检查安装状态和自动更新是否正常。

PATH 问题与常见报错

PATH 的修复写法（zsh 示例）：

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

各个错误码的详细含义可以对照 401 修复指南 和 错误码文档。

升级、多版本与卸载

装好之后，后续维护也有几个要点，提前了解可以少走弯路。

升级：原生安装方式默认会在后台自动更新，也可以手动执行 claude update 立即升级；npm 安装的执行 npm update -g @anthropic-ai/claude-code。升级只替换程序本身，环境变量和 ~/.claude 目录下的配置都不会丢，不需要重新接入。

多台机器：公司电脑、家里的 Mac、远程开发机各配一遍即可，可以共用同一把 Key，也可以每台机器单独建一把，后者在控制台里能直接看出每台机器的消耗，某台机器丢失时也只需要删掉对应的那把 Key。

卸载：npm 安装的执行 npm uninstall -g @anthropic-ai/claude-code；原生安装的删除安装目录中的 claude 可执行文件即可。如果想彻底清理，再删掉 ~/.claude 目录和 shell 配置文件里那两行变量。注意 ~/.claude 里保存着你的个人设置和自定义命令，删除前确认不再需要。

切换安装方式（比如从 npm 换到原生安装）时，先卸载旧的那份，再装新的，最后用 which -a claude 确认只剩一份。

服务器与远程开发

Linux 服务器上用 Claude Code 很常见，比如通过 SSH 登录开发机。几点建议：

• SSH 登录是登录 shell，确认 ~/.bash_profile 会加载 ~/.bashrc，否则变量不生效
• 长任务建议在 tmux 或 screen 里跑，SSH 断开不会中断会话
• 多人共用一台服务器时，每人用自己的系统用户和自己的 Key，不要把 Key 写进 /etc/profile 这种全局文件
• 公司网络需要代理时，设置 HTTPS_PROXY 环境变量即可

团队成员多的话，在 团队模式 里给每人发独立 Key 并设置日、月预算，用量可以按成员和 Key 拆开看，详见 团队 API Key 与预算管理。

常见问题 FAQ

Q：macOS 上装 Claude Code 需要先装 Node.js 吗？ A：不需要。官方原生安装脚本不依赖 Node.js，一条 curl 命令就能装好。只有选择 npm 安装方式时才需要 Node.js 18 及以上版本。

Q：环境变量写在 ~/.zshrc 和 settings.json 有什么区别？ A：写在 ~/.zshrc 对所有终端程序生效，其他工具也能读到；写在 ~/.claude/settings.json 的 env 字段只对 Claude Code 生效。建议只选其中一处配置，排查起来更简单。

Q：npm install -g 报 EACCES 权限错误怎么办？ A：不要加 sudo。把 npm 全局目录改到用户目录（npm config set prefix ~/.npm-global）并加入 PATH，或者直接改用官方原生安装脚本。

Q：配置完为什么还提示我登录 Anthropic 账号？ A：说明当前终端没读到变量。先 echo $ANTHROPIC_BASE_URL 检查，常见原因是写错了配置文件（zsh 写进了 ~/.bashrc）或没有重开终端。

Q：Linux 服务器上能用 Claude MAX 分组吗？ A：可以。Claude MAX 分组走原生 Anthropic 协议，与平台无关，在 Key 上选择分组即可，配置方式和本机完全一样。

Q：怎么在官方账号和 Zivv 之间切换？ A：注释掉配置文件里的两行变量（或删除 settings.json 里的 env）后重开终端，就会回到官方登录方式；临时切换可以在单个终端里 unset 这两个变量。

写在最后

macOS / Linux 上接入 Claude Code 的核心只有三件事：选一种安装方式并只装一份、把两个变量写进正确的配置文件、用控制台用量确认流量真的走了中转。Claude Code 的更多用法可以继续看 Claude Code 限速解决方案 和 官方文档；现在 注册 Zivv 创建 Key，几分钟就能跑起来。