macOS 安装流程

本教程按 macOS 上常见的安装顺序组织：先准备基础环境，再配置 Claude Code，然后安装 MCP、CCG Workflow、OpenSpec CLI 等进阶能力。

开始之前

安装内容一览

基础环境 — Homebrew、iTerm2、zsh、Starship、tmux、Git、Node.js、Claude Code

Claude Code 配置 — API 供应商配置、ccline 状态栏、Claude 基础配置、用户级 CLAUDE.md

进阶能力 — MCP 服务、CCG Workflow、OpenSpec CLI

完整安装需要较长时间，具体取决于网络速度和 API Key 准备情况。

系统要求

最低要求

操作系统：macOS 12 或更高版本
终端：Terminal、iTerm2、Warp、Ghostty 均可
网络：可访问 GitHub、npm registry、Claude Code 认证或第三方 API Endpoint

终端约定

本文默认使用 macOS 自带的 zsh。打开方式：

按 Command + Space
输入 Terminal
按 Enter 打开终端

如果终端或 iTerm2 打开后仍然进入 bash，先把默认登录 Shell 切换为 zsh：

bash

chsh -s /bin/zsh

执行后关闭并重新打开终端，再继续后续安装。

1. 准备网络与代理（可选）

如果你的网络可以稳定访问 GitHub、npm registry 和目标 API 服务，可以跳过本节。

代理工具

macOS 常见选择：

FlClash
Shadowrocket

启用代理后，先确认终端可以访问目标服务，再继续安装：

bash

curl -I https://github.com
npm view @anthropic-ai/claude-code version

2. 安装基础环境

这一节包含终端环境、Shell 提示符、Git、Node.js 和 Claude Code。

2.1 安装 Homebrew

Homebrew 是 macOS 常用包管理器，用来安装 iTerm2、Starship、tmux、Git、nvm 等工具。

bash

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装结束后，按终端提示把 Homebrew 写入 shell 环境。Apple Silicon Mac 通常执行：

bash

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Intel Mac 通常执行：

bash

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"

验证：

bash

brew --version

2.2 配置终端环境（iTerm2 + zsh + Starship + tmux）

iTerm2 是 macOS 上常用的增强终端；zsh 是 macOS Catalina 之后新用户默认使用的 Shell；Starship 用于美化和增强 Shell 提示符；tmux 用于在终端里管理多个会话、窗口和面板。

它们的关系可以理解为：

text

iTerm2 负责终端窗口和显示体验
zsh 负责执行命令和读取 ~/.zshrc
Starship 负责命令提示符外观和状态信息
tmux 负责会话保持、窗口和分屏

bash

brew install --cask iterm2
brew install starship tmux

配置 Starship：

bash

cat <<'EOF' >> ~/.zshrc

# >>> starship >>>
eval "$(starship init zsh)"
# <<< starship <<<
EOF
source ~/.zshrc

验证：

bash

open -a iTerm
starship --version
tmux -V

如果希望 iTerm2 成为打开脚本文件时的默认终端，在 iTerm2 菜单栏选择 iTerm2 → Make iTerm2 Default Term。

INFO

这个设置只影响 .command、.tool、.zsh、.csh、.pl 等文件的打开方式，并不是把 macOS 所有“打开终端”的入口都全局替换成 iTerm2。

常用 tmux 命令：

bash

# 新建会话
tmux new -s dev

# 断开当前会话
# 先按 Ctrl+b，再按 d

# 恢复会话
tmux attach -t dev

后续步骤可以继续在 iTerm2 中执行。

2.3 安装 Git

bash

brew install git

验证：

bash

git --version

推荐配置：

bash

git config --global core.quotepath false
git config --global pull.rebase false
git config --global init.defaultBranch main

2.4 安装 Node.js（nvm）

macOS 推荐使用 nvm 管理 Node.js，后续切换版本更方便。这里使用 nvm 官方安装脚本。

bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

如果安装脚本没有自动写入 ~/.zshrc，手动追加以下内容：

bash

cat <<'EOF' >> ~/.zshrc

# >>> nvm >>>
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"
# <<< nvm <<<
EOF

让当前终端立即生效：

bash

source ~/.zshrc

安装 LTS 版本 Node.js：

bash

nvm install --lts
nvm alias default 'lts/*'
nvm use default

验证：

bash

command -v nvm
node --version
npm --version

2.5 安装 Claude Code

bash

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

3. 配置 Claude Code 供应商

这一节用于选择 API Key、Base URL 和模型参数。下面整理了常见供应商需要填入最终合并版 settings.json 的 env 字段。

先创建配置目录，最终配置会在后面统一写入：

bash

mkdir -p ~/.claude

TIP

不要把多个 JSON 示例连续粘贴到 settings.json。最终文件只能有一个根对象，后续会给出合并后的完整版本。

安全提醒

API Key 是身份凭证，不要发给别人，不要提交到 Git 仓库，也不要粘贴到公开网页。

DeepSeek（推荐）

Key 获取地址：DeepSeek API Keys

json

{
  "ANTHROPIC_AUTH_TOKEN": "你的 DeepSeek API Key",
  "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
  "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
  "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash",
  "CLAUDE_CODE_EFFORT_LEVEL": "max"
}

智谱 GLM

Key 获取地址：智谱 GLM API Keys

json

{
  "ANTHROPIC_AUTH_TOKEN": "你的智谱 API Key",
  "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.1",
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.1",
  "API_TIMEOUT_MS": "3000000"
}

MiniMax

Key 获取地址：MiniMax Interface Key

json

{
  "ANTHROPIC_AUTH_TOKEN": "你的 MiniMax API Key",
  "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
  "ANTHROPIC_MODEL": "MiniMax-M2.7",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-M2.7",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "MiniMax-M2.7",
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M2.7",
  "API_TIMEOUT_MS": "3000000"
}

Kimi Code

Key 获取地址：Kimi Code Console

json

{
  "ANTHROPIC_AUTH_TOKEN": "你的 Kimi Code API Key",
  "ANTHROPIC_BASE_URL": "https://api.kimi.com/coding/",
  "ANTHROPIC_MODEL": "kimi-for-coding",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "kimi-for-coding",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "kimi-for-coding",
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-for-coding",
  "CLAUDE_CODE_SUBAGENT_MODEL": "kimi-for-coding",
  "ENABLE_TOOL_SEARCH": "false"
}

阿里云百炼

Key 获取地址：阿里云百炼 Coding Plan

百炼需要按平台实际可用模型填写 3 个模型键：

json

{
  "ANTHROPIC_AUTH_TOKEN": "你的阿里云百炼 API Key",
  "ANTHROPIC_BASE_URL": "https://coding.dashscope.aliyuncs.com/apps/anthropic",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "填写百炼可用的轻量模型",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "填写百炼可用的高能力模型",
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "填写百炼可用的中高能力模型"
}

自定义供应商

如果你使用其他 Anthropic 兼容接口，按供应商文档填写 Base URL、API Key 和模型名：

json

{
  "ANTHROPIC_AUTH_TOKEN": "你的 API Key",
  "ANTHROPIC_BASE_URL": "https://api.example.com/anthropic",
  "ANTHROPIC_MODEL": "供应商支持的默认模型",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "供应商支持的轻量模型",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "供应商支持的高能力模型",
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "供应商支持的中高能力模型",
  "CLAUDE_CODE_SUBAGENT_MODEL": "供应商支持的子代理模型"
}

4. 配置与安装进阶能力

建议先完成基础环境验证，再逐项配置和安装。

4.1 安装 ccline 状态栏

bash

npm install -g @cometix/ccline

验证：

bash

ccline --version

4.2 写入最终合并版 `settings.json`

打开配置文件：

bash

nano ~/.claude/settings.json

下面是合并后的完整结构，已经同时包含供应商 env、ccline 状态栏、Claude 基础配置、权限和 attribution。把 env 里的供应商字段替换成上一节选定供应商对应的内容即可。

json

{
  "language": "简体中文",
  "alwaysThinkingEnabled": true,
  "showThinkingSummaries": true,
  "plansDirectory": ".claude/plan",
  "statusLine": {
    "type": "command",
    "command": "ccline",
    "padding": 0
  },
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的 API Key",
    "ANTHROPIC_BASE_URL": "https://api.example.com/anthropic",
    "ANTHROPIC_MODEL": "供应商支持的默认模型",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "供应商支持的轻量模型",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "供应商支持的高能力模型",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "供应商支持的中高能力模型",
    "CLAUDE_CODE_SUBAGENT_MODEL": "供应商支持的子代理模型",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "90",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "DISABLE_INSTALLATION_CHECKS": "1",
    "MAX_THINKING_TOKENS": "31999"
  },
  "permissions": {
    "allow": [
      "Bash",
      "BashOutput",
      "Edit",
      "Glob",
      "Grep",
      "KillShell",
      "NotebookEdit",
      "Read",
      "SlashCommand",
      "Task",
      "TodoWrite",
      "WebFetch",
      "WebSearch",
      "Write",
      "mcp__context7",
      "mcp__deepwiki"
    ],
    "deny": []
  },
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

WARNING

如果 ~/.claude/settings.json 已经存在，不要直接覆盖整份文件；请把缺少的字段合并进去，尤其不要覆盖已有的 API Key、OAuth、MCP 或项目相关配置。

4.3 完成初始化

写入配置后，如果 ~/.claude.json 不存在，可以创建初始化标记；如果文件已存在，不要覆盖，保留 Claude Code 已写入的 OAuth、MCP 和项目状态信息。

bash

if [ ! -f ~/.claude.json ]; then
  cat > ~/.claude.json <<'EOF'
{
  "hasCompletedOnboarding": true
}
EOF
else
  echo "~/.claude.json 已存在，跳过创建。"
fi

验证启动：

bash

claude

4.4 写入用户级 CLAUDE.md

用户级 ~/.claude/CLAUDE.md 用来保存 Claude Code 的全局工作规范。它会在不同项目中复用，适合放通用协作原则，不适合放某个项目的私有实现细节。

WARNING

如果你已经有自己的 ~/.claude/CLAUDE.md，不要直接覆盖；下面的命令会在文件已存在时跳过写入，请手动合并需要的规则。

bash

if [ ! -f ~/.claude/CLAUDE.md ]; then
  cat > ~/.claude/CLAUDE.md <<'EOF'
# Claude Code 增强配置

## 一、核心原则

### 调研优先（强制）
修改代码前必须：1) 检索相关代码 2) 识别复用机会 3) 追踪调用链影响范围

### 修改前三问
1. 这是真问题还是臆想？（拒绝过度设计）
2. 有现成代码可复用吗？（优先复用）
3. 会破坏什么调用关系？（保护依赖链）

### 红线原则
- 禁止 copy-paste 重复代码；禁止破坏现有功能；禁止对错误方案妥协
- 禁止盲目执行不加思考；禁止基于假设回答（必须检索验证）
- 关键路径必须有错误处理

### 安全检查
- 禁止硬编码密钥/密码/token；不提交 .env / credentials 等敏感文件
- 用户输入在系统边界必须验证

### 代码风格
- **KISS** - 能简单就不复杂 | **DRY** - 零容忍重复，必须复用
- **保护调用链** - 修改函数签名时同步更新所有调用点
- 完成后清理：临时文件、废弃代码、未使用导入、调试日志

---

## 二、工作流原则

1. **先检索，后生成** - 修改代码前必须先检索相关代码
2. **增强需求** - 复杂任务先明确需求边界

---

## 三、任务分级

| 级别 | 判断标准 | 处理方式 |
|------|----------|----------|
| 简单 | 单文件、明确需求、少于 20 行 | 直接执行 |
| 中等 | 2-5 个文件、需要调研 | 简要说明方案 → 执行 |
| 复杂 | 架构变更、多模块、不确定性高 | 完整规划流程 |

### 复杂任务流程
1. **RESEARCH** - 调研代码，不提建议
2. **PLAN** - 列出方案，等待用户确认
3. **EXECUTE** - 严格按计划执行
4. **REVIEW** - 完成后自检

触发：用户说“进入 X 模式”或任务符合复杂标准时自动启用

---

## 四、交互与环境

### 何时询问用户
- 存在多个合理方案时；需求不明确或有歧义时
- 改动范围超出预期时；发现潜在风险时

### 何时直接执行
- 需求明确且方案唯一；小范围修改（少于 20 行）；用户已确认过类似操作

### 敢于说不
发现问题直接指出，不妥协于错误方案

### 环境特定（macOS / zsh）
- 优先使用 Homebrew 安装开发工具
- Shell 配置优先写入 `~/.zshrc`，Homebrew 环境初始化写入 `~/.zprofile`
- 中文路径、包含空格的路径必须用双引号包裹

### 输出设置
- 中文响应；禁用表情符号；禁止截断输出
EOF
else
  echo "~/.claude/CLAUDE.md 已存在，请手动合并配置。"
fi

验证文件存在并可读取：

bash

test -s ~/.claude/CLAUDE.md && sed -n '1,20p' ~/.claude/CLAUDE.md

4.5 安装 MCP 服务

推荐先安装无凭据的 MCP，降低排错难度。

Context7

bash

claude mcp add -s user context7 -- npx -y @upstash/context7-mcp

DeepWiki

bash

claude mcp add -s user -t http deepwiki https://mcp.deepwiki.com/mcp

验证：

bash

claude

进入 Claude Code 后输入：

text

/mcp

如果 MCP 服务显示已连接，说明配置成功。

4.6 安装 CCG Workflow

CCG Workflow 是可选的多模型工作流能力。

bash

npx --yes ccg-workflow@latest init --skip-prompt --skip-mcp --lang zh-CN --install-dir "$HOME/.claude"

验证：

bash

claude

进入 Claude Code 后输入：

text

/ccg

如果能看到带 ccg 前缀的命令，说明安装成功。

4.7 安装 OpenSpec CLI

bash

npm install -g @fission-ai/openspec
openspec --version

下一步

完成安装后，可以继续阅读：

文档	内容
常用配置	Claude Code 配置、权限和模型设置
快捷键	提升 Claude Code 操作效率
MCP 服务	扩展外部工具和数据源
Skills	使用模块化能力扩展 Claude Code
工作流	CCG Workflow 与多模型协作
AI 辅助工具	CC Switch、EnsoAI、Cherry Studio、Aether 等工具

macOS 安装流程 ​

开始之前 ​

安装内容一览 ​

系统要求 ​

终端约定 ​

1. 准备网络与代理（可选） ​

代理工具 ​

2. 安装基础环境 ​

2.1 安装 Homebrew ​

2.2 配置终端环境（iTerm2 + zsh + Starship + tmux） ​

2.3 安装 Git ​

2.4 安装 Node.js（nvm） ​

2.5 安装 Claude Code ​

3. 配置 Claude Code 供应商 ​

DeepSeek（推荐） ​

智谱 GLM ​

MiniMax ​

Kimi Code ​

阿里云百炼 ​

自定义供应商 ​

4. 配置与安装进阶能力 ​

4.1 安装 ccline 状态栏 ​

4.2 写入最终合并版 settings.json ​

4.3 完成初始化 ​

4.4 写入用户级 CLAUDE.md ​

4.5 安装 MCP 服务 ​

Context7 ​

DeepWiki ​

4.6 安装 CCG Workflow ​

4.7 安装 OpenSpec CLI ​

下一步 ​

macOS 安装流程

开始之前

安装内容一览

系统要求

终端约定

1. 准备网络与代理（可选）

代理工具

2. 安装基础环境

2.1 安装 Homebrew

2.2 配置终端环境（iTerm2 + zsh + Starship + tmux）

2.3 安装 Git

2.4 安装 Node.js（nvm）

2.5 安装 Claude Code

3. 配置 Claude Code 供应商

DeepSeek（推荐）

智谱 GLM

MiniMax

Kimi Code

阿里云百炼

自定义供应商

4. 配置与安装进阶能力

4.1 安装 ccline 状态栏

4.2 写入最终合并版 `settings.json`

4.3 完成初始化

4.4 写入用户级 CLAUDE.md

4.5 安装 MCP 服务

Context7

DeepWiki

4.6 安装 CCG Workflow

4.7 安装 OpenSpec CLI

下一步