macOS 安装 Claude Code 全流程

摘要 ：Mac 上安装 Claude Code 比 Windows 简单得多------原生安装器、Homebrew、npm 三条路，五分钟搞定。但 macOS 有自己的一套"安全机制"（Keychain、Gatekeeper、TCC 权限），不搞清楚容易卡在莫名其妙的地方。这篇把三条路和四个 macOS 特有的坑都讲清楚。

适用读者 ：macOS 13.0+ 用户（Intel 和 Apple Silicon 都支持）

前置知识 ：会用终端即可，建议先看第 09 篇了解订阅方式

预计阅读时间 ：10 分钟

适用版本：Claude Code 2.x（2026 年 7 月）

---

一、引言

上篇把 Windows 安装讲完了。评论区有条 Mac 用户的留言把我逗乐了------

"看完了 Windows 教程，感觉 Mac 用户被遗忘了。"

没有的事。这篇就是你们的。

说实话，在 Mac 上装 Claude Code 比 Windows 省心太多了。macOS 本身就是 Unix 系统，和 Claude Code 的 Linux-first 设计天然契合。没有"Git Bash 找不到"的烦恼，没有 WSL 和原生 Windows 的选择困难------三条命令，选一条，五分钟搞定。

但 macOS 也有自己的一套"脾气"------Keychain 钥匙串、Gatekeeper 门禁、TCC 隐私权限。不搞清楚，容易在莫名其妙的地方卡住。这篇就把这些都讲明白。

---

二、开始之前：环境检查

打开终端（在"启动台 → 其他 → 终端"，或 Spotlight 搜索"Terminal"），依次敲入：

2.1 确认 macOS 版本

sw_vers

预期结果 ：ProductVersion 应该是 13.0 或更高。

Claude Code 最低要求 macOS 13（Ventura）。如果你的 Mac 还在 macOS 12 或更早------该升级了。不是 Claude Code 矫情，是它依赖的一些系统组件在旧版本上确实跑不起来。

Intel Mac 还是 Apple Silicon？

uname -m

• arm64 → Apple Silicon（M1/M2/M3/M4）
• x86_64 → Intel

两种都完全支持。不用担心兼容性。

2.2 确认 Xcode Command Line Tools

xcode-select -p

预期结果 ：显示一个路径，比如 /Library/Developer/CommandLineTools 或 /Applications/Xcode.app/...。

如果没有------Claude Code 的某些编译相关功能会报错。安装：

xcode-select --install

弹窗点"安装"，等两分钟就好。不需要装完整的 Xcode（十几个 G），Command Line Tools 就够了（几百 MB）。

---

三、三种安装方法（推荐第一种）

方法一：原生安装器（⭐ 最推荐）

优点 ：一条命令，自带 Node.js 运行时，后台自动更新

适合：所有 Mac 用户

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

你会看到：终端里跑几行进度信息，最后显示安装成功。

安装位置：~/.local/bin/claude

验证：

claude --version

预期结果 ：Claude Code v2.x.x

如果提示 command not found: claude------说明 ~/.local/bin 不在 PATH 里。跳到第五部分看"问题 1"。

方法二：Homebrew 安装

优点 ：统一用 Homebrew 管理所有工具，适合有 Brewfile 管理习惯的开发者

缺点：不会自动更新，版本通常比原生安装器慢一周左右

brew install --cask claude-code

⚠️ 注意别装错包名！ Homebrew 上有两个 Claude 相关的 cask：

包名	是什么
claude-code	Claude Code CLI（你要的这个）
claude	Claude Desktop 桌面应用（不是你要的）

装错了的话------你会得到一个桌面 GUI 而不是命令行工具。

更新：

brew upgrade claude-code

卸载：

brew uninstall claude-code

方法三：npm 全局安装

优点 ：和你的 Node.js 项目工具链统一

缺点：需要 Node.js 18+，不会自动更新

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

macOS 上的 npm 特别提醒 ：绝对不要加 sudo。 macOS 上用 sudo npm install -g 会导致 ~/.npm 目录的权限被 root 接管，以后所有 npm 操作都需要 sudo------这是一个经典的"自毁"操作。

如果不小心已经用了 sudo------修复方法见第五部分"问题 2"。

---

三种方法对比

方法	命令	自动更新	需要 Node	需要 Homebrew	推荐度
原生安装器	`curl ...	bash`	✅	❌	❌
Homebrew	brew install --cask ...	❌	❌	✅	⭐⭐⭐⭐
npm	npm install -g ...	❌	✅	❌	⭐⭐⭐

我的建议：如果你不是 Homebrew 重度用户------直接用原生安装器，最简单最省心。如果你已经在用 Homebrew 管理所有开发工具------用 Homebrew，风格统一。

---

四、首次启动与登录

装好之后：

cd ~/your-project
claude

首次启动会引导你登录。在 Mac 上，OAuth 登录凭证会自动存到系统钥匙串（Keychain）里------这是 macOS 独有的优势，比 Linux 上存明文文件安全得多。

4.1 OAuth 登录（订阅用户）

浏览器自动打开 → 登录 claude.ai 账号 → 授权 → 自动跳回终端。

一切顺利的话，30 秒完事。

验证：

/status

你会看到：

Account: you@email.com (Pro)
Auth: Claude subscription (OAuth)
Model: sonnet (Sonnet 4.6)

4.2 API Key 登录（按量付费用户）

# 临时设置（仅当前终端窗口）
export ANTHROPIC_API_KEY="sk-ant-api03-你的key"

# 永久设置（写入 shell 配置）
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-你的key"' >> ~/.zshrc
source ~/.zshrc

然后启动 claude。

🔐 Mac 用户专属技巧------把 API Key 存进 Keychain：

不推荐把 API Key 明文写在 ~/.zshrc 里------任何能读你 dotfile 的程序都能看到它。更安全的做法是存到钥匙串：

# 存储（只需执行一次）
security add-generic-password -a "$USER" -s "anthropic-api-key" -w "sk-ant-api03-你的key"

# 然后在 ~/.zshrc 里加这行（每次打开终端自动从 Keychain 读取）
echo 'export ANTHROPIC_API_KEY=$(security find-generic-password -a "$USER" -s "anthropic-api-key" -w 2>/dev/null)' >> ~/.zshrc

这样你的 API Key 只存在于加密的钥匙串里，不会以明文出现在任何文件中。

4.3 别忘了 /status 检查

不管用哪种方式登录，启动后第一件事------敲 /status。

确认 Auth 那行是你想走的路径。如果你之前用过 API Key 后来又买了订阅------API Key 可能悄悄覆盖了你的订阅额度。这个坑我在第 09 篇详细讲过，Mac 上同样适用。

---

五、macOS 特有的坑与解决方案

问题 1：command not found: claude

原因 ：~/.local/bin 不在 PATH 里。macOS 的默认 PATH 不包含这个目录。

你用的 shell 是什么？ 先确认：

echo $SHELL

• /bin/zsh → macOS 默认（Catalina 及之后）
• /bin/bash → 旧版 macOS 默认

zsh 用户（大部分人）：

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

bash 用户：

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

关掉终端重新打开，再试 claude --version。

问题 2：npm 全局安装报 EACCES 权限错误

原因：npm 的全局目录是系统目录，需要 root 权限。这是 macOS 上 npm 最常见的坑。

解决------不要用 sudo。 把 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。

如果之前已经用 sudo 搞乱了权限：

# 把 ~/.npm 目录的所有权拿回来
sudo chown -R $(whoami) ~/.npm
# 然后把全局目录切到用户目录（同上）

问题 3：Gatekeeper 拦截------"无法验证开发者"

现象：首次启动时弹窗"无法验证'claude'的开发者。您确定要打开它吗？"

原因：macOS Gatekeeper（门禁）对未签名的二进制文件会拦截。

解决：

1. 打开"系统设置 → 隐私与安全性"
2. 往下滚，找到"安全性"区域
3. 你会看到一条关于 claude 被阻止的信息，旁边有一个"仍要打开"按钮
4. 点它，输入密码确认

或者用命令行清除隔离标记：

xattr -d com.apple.quarantine ~/.local/bin/claude

两种方法效果一样，选一个就行。

问题 4：Keychain 反复要求登录

现象：每次启动 Claude Code 都要重新登录，明明上次登录过了。

原因：macOS 钥匙串被锁定，或者终端没有访问钥匙串的权限。Claude Code 的 OAuth token 存在钥匙串里，读不到就只能重登。

排查：

首先，跑诊断：

claude doctor

这个命令会检查 Keychain 访问状态并告诉你哪里不对。

然后，打开"钥匙串访问"应用（在"实用工具"里），搜索"anthropic"------看看有没有 Claude Code 相关的条目。如果有，双击打开，确认"访问控制"设置允许你的终端应用访问。

如果钥匙串被锁了------左侧"登录"钥匙串上右键 → 锁定，再右键 → 解锁。

终极方案------如果钥匙串一直有问题，改用 API Key 方式登录（见 4.2），绕过 Keychain。记得把 Key 存到 Keychain 而不是明文------有点讽刺，但确实能用。

问题 5：终端没有"完全磁盘访问"权限

现象：Claude Code 可以启动，但读写某些目录时提示权限不足。

原因：macOS 从 Catalina 开始引入了 TCC（透明度、同意与控制）框架，对应用访问文件系统有严格限制。你的终端应用（Terminal.app / iTerm2 等）需要获得"完全磁盘访问"权限才能让 Claude Code 自由操作项目文件。

解决：

1. "系统设置 → 隐私与安全性 → 完全磁盘访问"
2. 点 "+" 号
3. 找到你的终端应用（Terminal.app 或 iTerm.app 等），添加
4. 如果锁是锁着的，点左下角的锁图标解锁
5. 重启终端

问题 6：Xcode MCP 工具权限无限挂起

现象：如果你装了 Xcode MCP（让 Claude Code 操作 Xcode 的扩展），某些操作会一直转圈、没有响应。

原因：macOS 的自动化权限系统无法为 CLI 工具（没有稳定的 Bundle ID）持久化授权。

表现：每次使用 Xcode 相关工具都会弹权限确认框，点"允许"后下次还是要重新授权；有时候工具调用直接超时。

这个 Bug 在 GitHub 上有追踪（Issue #23550），目前还未完全修复。如果你不用 Xcode MCP------完全不关你的事，跳过这段。

如果你用 Xcode MCP------可以试试社区提供的 xcode-mcp-manager 包来缓解。

---

六、常用管理命令

不管你用哪种方法装的，以下命令都一样好用：

# 查看版本
claude --version

# 全面体检（Keychain、PATH、权限、网络）
claude doctor

# 启动后
/status       # 查看当前认证状态和模型
/doctor       # 会话内诊断
/model sonnet # 切换到 Sonnet（日常开发）
/model opus   # 切换到 Opus（复杂任务）
/init         # 为当前项目生成 CLAUDE.md

# 登出
claude logout

# 重新登录
claude login

---

七、装完后的第一件事

和 Windows 篇说的一样------/init。

进入你的项目目录，启动 Claude Code，敲 /init。30 秒生成 CLAUDE.md。这是 Claude Code 了解你项目的"说明书"------跳过这步的人，用了一周就开始吐槽"AI 不懂我的项目"。

---

八、总结与下篇预告

本文要点

• 三条安装路，原生安装器最省心------自带 Node.js，自动更新，一条命令搞定
• 环境检查两步走------macOS 13.0+、Xcode Command Line Tools
• Mac 专属福利------OAuth 凭证自动存 Keychain，安全又省心
• API Key 别明文写 dotfile 里 ------用 security 命令存钥匙串
• Gatekeeper 拦截 ------去系统设置点"仍要打开"，或者 xattr -d 一行解决
• 终端需要完全磁盘访问权限------在隐私与安全性里加一下，一劳永逸

Mac 上装 Claude Code 的时间预算

你的情况	预计耗时
纯新手，第一次用终端	15 分钟
普通开发者	5 分钟
有 Homebrew 的老手	3 分钟

下篇预告

Windows 搞定了，Mac 搞定了。Linux 用户------你们的回合到了。

下一篇，Linux 安装完整指南。Ubuntu、Debian、Fedora、Arch、CentOS------不同发行版的安装差异、snap 和原生安装器的选择、以及 Linux 上独有的权限和 Wayland/X11 问题。

三大平台凑齐，全家桶就完整了。

---

参考资源：

• Claude Code 官方安装文档
• Claude Code 安装与认证故障排除
• Claude Code 用户 FAQ

声明：本文基于 Claude Code 2.x 版本（2026 年 7 月）编写，在 macOS 14（Sonoma）和 macOS 15（Sequoia）上实测通过。Apple Silicon 和 Intel Mac 均支持。安装命令和路径可能随版本更新变化。