摘要Mac 上安装 Claude Code 比 Windows 简单得多——原生安装器、Homebrew、npm 三条路五分钟搞定。但 macOS 有自己的一套安全机制Keychain、Gatekeeper、TCC 权限不搞清楚容易卡在莫名其妙的地方。这篇把三条路和四个 macOS 特有的坑都讲清楚。适用读者macOS 13.0 用户Intel 和 Apple Silicon 都支持前置知识会用终端即可建议先看第 09 篇了解订阅方式预计阅读时间10 分钟适用版本Claude Code 2.x2026 年 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 13Ventura。如果你的 Mac 还在 macOS 12 或更早——该升级了。不是 Claude Code 矫情是它依赖的一些系统组件在旧版本上确实跑不起来。Intel Mac 还是 Apple Siliconuname-marm64→ Apple SiliconM1/M2/M3/M4x86_64→ Intel两种都完全支持。不用担心兼容性。2.2 确认 Xcode Command Line Toolsxcode-select-p预期结果显示一个路径比如/Library/Developer/CommandLineTools或/Applications/Xcode.app/...。如果没有——Claude Code 的某些编译相关功能会报错。安装xcode-select--install弹窗点安装等两分钟就好。不需要装完整的 Xcode十几个 GCommand Line Tools 就够了几百 MB。三、三种安装方法推荐第一种方法一原生安装器⭐ 最推荐优点一条命令自带 Node.js 运行时后台自动更新适合所有 Mac 用户curl-fsSLhttps://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 管理习惯的开发者缺点不会自动更新版本通常比原生安装器慢一周左右brewinstall--caskclaude-code⚠️ 注意别装错包名Homebrew 上有两个 Claude 相关的 cask包名是什么claude-codeClaude CodeCLI你要的这个claudeClaudeDesktop桌面应用不是你要的装错了的话——你会得到一个桌面 GUI 而不是命令行工具。更新brew upgrade claude-code卸载brew uninstall claude-code方法三npm 全局安装优点和你的 Node.js 项目工具链统一缺点需要 Node.js 18不会自动更新npminstall-ganthropic-ai/claude-codemacOS 上的 npm 特别提醒绝对不要加sudo。macOS 上用sudo npm install -g会导致~/.npm目录的权限被 root 接管以后所有 npm 操作都需要 sudo——这是一个经典的自毁操作。如果不小心已经用了 sudo——修复方法见第五部分问题 2。三种方法对比方法命令自动更新需要 Node需要 Homebrew推荐度原生安装器curl … | bash✅❌❌⭐⭐⭐⭐⭐Homebrewbrew install --cask …❌❌✅⭐⭐⭐⭐npmnpm install -g …❌✅❌⭐⭐⭐我的建议如果你不是 Homebrew 重度用户——直接用原生安装器最简单最省心。如果你已经在用 Homebrew 管理所有开发工具——用 Homebrew风格统一。四、首次启动与登录装好之后cd~/your-project claude首次启动会引导你登录。在 Mac 上OAuth 登录凭证会自动存到系统钥匙串Keychain里——这是 macOS 独有的优势比 Linux 上存明文文件安全得多。4.1 OAuth 登录订阅用户浏览器自动打开 → 登录 claude.ai 账号 → 授权 → 自动跳回终端。一切顺利的话30 秒完事。验证/status你会看到Account: youemail.com (Pro) Auth: Claude subscription (OAuth) Model: sonnet (Sonnet 4.6)4.2 API Key 登录按量付费用户# 临时设置仅当前终端窗口exportANTHROPIC_API_KEYsk-ant-api03-你的key# 永久设置写入 shell 配置echoexport ANTHROPIC_API_KEYsk-ant-api03-你的key~/.zshrcsource~/.zshrc然后启动claude。 Mac 用户专属技巧——把 API Key 存进 Keychain不推荐把 API Key 明文写在~/.zshrc里——任何能读你 dotfile 的程序都能看到它。更安全的做法是存到钥匙串# 存储只需执行一次security add-generic-password-a$USER-santhropic-api-key-wsk-ant-api03-你的key# 然后在 ~/.zshrc 里加这行每次打开终端自动从 Keychain 读取echoexport 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 特有的坑与解决方案问题 1command not found: claude原因~/.local/bin不在 PATH 里。macOS 的默认 PATH 不包含这个目录。你用的 shell 是什么先确认echo$SHELL/bin/zsh→ macOS 默认Catalina 及之后/bin/bash→ 旧版 macOS 默认zsh 用户大部分人echoexport PATH$HOME/.local/bin:$PATH~/.zshrcsource~/.zshrcbash 用户echoexport PATH$HOME/.local/bin:$PATH~/.bash_profilesource~/.bash_profile关掉终端重新打开再试claude --version。问题 2npm 全局安装报 EACCES 权限错误原因npm 的全局目录是系统目录需要 root 权限。这是 macOS 上 npm 最常见的坑。解决——不要用 sudo。把 npm 全局目录改成用户目录mkdir-p~/.npm-globalnpmconfigsetprefix~/.npm-globalechoexport PATH$HOME/.npm-global/bin:$PATH~/.zshrcsource~/.zshrc然后重新执行npm install -g anthropic-ai/claude-code。如果之前已经用 sudo 搞乱了权限# 把 ~/.npm 目录的所有权拿回来sudochown-R$(whoami)~/.npm# 然后把全局目录切到用户目录同上问题 3Gatekeeper 拦截——“无法验证开发者”现象首次启动时弹窗无法验证’claude’的开发者。您确定要打开它吗原因macOS Gatekeeper门禁对未签名的二进制文件会拦截。解决打开系统设置 → 隐私与安全性往下滚找到安全性区域你会看到一条关于claude被阻止的信息旁边有一个仍要打开按钮点它输入密码确认或者用命令行清除隔离标记xattr-dcom.apple.quarantine ~/.local/bin/claude两种方法效果一样选一个就行。问题 4Keychain 反复要求登录现象每次启动 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 自由操作项目文件。解决“系统设置 → 隐私与安全性 → 完全磁盘访问”点 “” 号找到你的终端应用Terminal.app 或 iTerm.app 等添加如果锁是锁着的点左下角的锁图标解锁重启终端问题 6Xcode 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# 登出claudelogout# 重新登录claude login七、装完后的第一件事和 Windows 篇说的一样——/init。进入你的项目目录启动 Claude Code敲/init。30 秒生成 CLAUDE.md。这是 Claude Code 了解你项目的说明书——跳过这步的人用了一周就开始吐槽AI 不懂我的项目。八、总结与下篇预告本文要点三条安装路原生安装器最省心——自带 Node.js自动更新一条命令搞定环境检查两步走——macOS 13.0、Xcode Command Line ToolsMac 专属福利——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 14Sonoma和 macOS 15Sequoia上实测通过。Apple Silicon 和 Intel Mac 均支持。安装命令和路径可能随版本更新变化。