macOS 平台指南

本教程主线以 Windows (Git Bash) 编写，大部分命令在 macOS 上可直接运行。本页记录 macOS 特有的配置和工具。

环境准备

安装

# 1. Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Node.js
brew install node

# 3. Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 4. 常用工具
brew install jq      # JSON 处理（Hooks 章节需要）
brew install tmux    # Agent Teams 分屏显示

Shell 配置

# macOS 默认使用 zsh
# 环境变量放在 ~/.zshrc
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

# 如果使用 bash
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bash_profile
source ~/.bash_profile

macOS 增强工具

Claude Code Monitor（Raycast 扩展）

claude-code-monitor 是一个 Raycast 扩展，提供 Claude Code 会话监控面板。

功能：

• 实时会话追踪（状态、费用、token）
• 菜单栏状态图标（颜色编码）
• 使用量分析面板（费用趋势、模型分布）
• 插件/Skill/MCP 管理

安装：

# 需要先安装 Raycast
# https://www.raycast.com/

# 安装扩展
# 在 Raycast Store 搜索 "Claude Code Monitor"
# 或从 GitHub 克隆后手动安装

git clone https://github.com/wuyuxiangX/claude-code-monitor.git
cd claude-code-monitor
npm install && npm run build
# 在 Raycast 中导入为开发者扩展

工作原理：

• 通过 Claude Code hooks 捕获会话生命周期事件
• Python 脚本将元数据写入 ~/.claude/claude-code-monitor/sessions.json
• 扩展读取 JSON + 解析 JSONL transcript 用于分析
• 全部本地处理 -- 无数据外传

支持的编辑器：VS Code, Cursor, Zed, Windsurf, IntelliJ, WebStorm, PyCharm, GoLand

支持的终端：Terminal.app, iTerm2, Warp, Ghostty, kitty, tmux

Computer Use（桌面自动化）

macOS 上的 Claude Code Desktop 支持 Computer Use -- 自动操控鼠标和键盘。

# 无需额外配置 -- 在 Claude Code Desktop 中开箱即用
# Claude 可以：
# - 移动鼠标并点击
# - 在应用间切换
# - 操作桌面文件
# - 与 Web 应用交互

注意：Computer Use 目前仅在 macOS 上的 Claude Code Desktop 中可用。

各章节 macOS 要点

Ch5 Hooks -- 通知音

# macOS 下播放通知音
afplay /System/Library/Sounds/Glass.aiff

# 或者使用语音朗读
say "Claude has finished the task"

# 发送系统通知
osascript -e 'display notification "Task complete" with title "Claude Code"'

Ch9 Agent Teams -- tmux 分屏

# macOS 支持 tmux，Agent Teams 可以使用分屏模式
brew install tmux

# Claude Code 会自动检测 tmux 可用性
# 启动 Agent Teams 时会创建分屏面板

# iTerm2 也支持原生分屏
# Cmd+D 垂直分屏，Cmd+Shift+D 水平分屏

Ch10 权限 -- Managed Policy 路径

# macOS 上的 managed policy 路径
# /Library/Application Support/ClaudeCode/managed-settings.json
# /Library/Application Support/ClaudeCode/managed-settings.d/*.json
# /Library/Application Support/ClaudeCode/CLAUDE.md

# 需要 sudo 权限写入
sudo mkdir -p "/Library/Application Support/ClaudeCode"
sudo cp managed-settings.json "/Library/Application Support/ClaudeCode/"

Ch11 IDE -- Desktop App

# macOS 上 Claude Code Desktop 提供额外功能：
# - 可视化文件 diff 审查
# - 实时应用预览（内嵌浏览器）
# - 多会话并行管理
# - 定时任务调度
# - Computer Use 桌面自动化

# 下载地址：https://claude.ai/download

常见问题

Q：权限问题

# 如果 Claude Code 需要访问特定目录，
# macOS 可能弹出权限请求对话框。
# 确保在 System Settings > Privacy & Security 中授权。

# Terminal 需要 "Full Disk Access" 权限
# System Settings > Privacy & Security > Full Disk Access > Terminal.app

Q：Homebrew 安装的 Node.js 与 nvm 冲突

# 如果同时有 Homebrew 和 nvm 安装的 Node.js，
# 确保 PATH 中 nvm 优先
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

# 验证使用的是哪个 node
which node
# 应该是 ~/.nvm/versions/node/... 而非 /opt/homebrew/bin/node

Q：Apple Silicon (M1/M2/M3/M4) 兼容性

# Claude Code 在 Apple Silicon 上完全兼容
# 如果某些 npm 包有原生依赖，确保使用 ARM 版本
node -p "process.arch"
# 应该输出 "arm64"

# 如果需要 x86 兼容
arch -x86_64 npm install