MacBook 安装配置 Claude Code 完整指南

从零开始配置 Claude Code + MiniMax API + 文档处理技能

写在前面

Claude Code 是 Anthropic 推出的 AI 编程助手，可以帮助你处理各种开发任务。本文将详细介绍如何在 MacBook 上完整配置 Claude Code，包括 MiniMax API 的对接、文档处理技能的安装，以及 CLAUDE.md 的初始化。

一、安装 Claude Code

1.1 环境要求

在开始之前，请确保你的 MacBook 满足以下要求：

macOS 12.0 或更高版本
已安装 Homebrew（推荐）
终端命令行基础操作能力

1.2 安装步骤

步骤一：安装 Claude Code CLI

打开终端，执行以下命令安装 Claude Code：

# 使用 npm 全局安装
npm install -g @anthropic-ai/claude-code

# 或者使用 Homebrew 安装
brew install claude-code

步骤二：验证安装

安装完成后，验证 Claude Code 是否安装成功：

claude --version

如果显示版本号，说明安装成功。

步骤三：首次启动

claude

首次启动时，Claude Code 会引导你完成初始配置。

二、配置 MiniMax API

2.1 为什么选择 MiniMax？

Claude Code 默认使用 Anthropic 的 Claude 模型，但国内访问 Anthropic API 可能存在网络限制。MiniMax 提供了兼容的 API 接口，是一个很好的替代选择。

2.2 获取 MiniMax API Key

访问 MiniMax 开放平台
注册/登录账号
进入「API Key」管理页面
创建新的 API Key

注意：请妥善保存你的 API Key，它只会显示一次。

2.3 配置环境变量

在终端中配置 MiniMax API：

# 临时生效（当前终端会话有效）
export MINIMAX_API_KEY="your-api-key-here"
export MINIMAX_API_BASE="https://api.minimax.chat/v1"

# 永久生效（写入 ~/.zshrc 或 ~/.bash_profile）
echo 'export MINIMAX_API_KEY="your-api-key-here"' >> ~/.zshrc
echo 'export MINIMAX_API_BASE="https://api.minimax.chat/v1"' >> ~/.zshrc
source ~/.zshrc

2.4 配置 Claude Code 使用 MiniMax

Claude Code 使用 claude Python 包，你可以创建配置文件来指定模型：

# 创建配置文件
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "model": "MiniMax-M2.5",
  "max_tokens": 4096,
  "api_base": "https://api.minimax.chat/v1",
  "api_key": "your-minimax-api-key"
}
EOF

或者在项目根目录创建 .claude.json：

cat > .claude.json << 'EOF'
{
  "model": "MiniMax-M2.5",
  "max_tokens": 4096
}
EOF

2.5 测试 API 连接

创建一个简单的测试脚本：

# 创建 test_api.py
cat > test_api.py << 'EOF'
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.getenv("MINIMAX_API_KEY"),
    base_url=os.getenv("MINIMAX_API_BASE", "https://api.minimax.chat/v1")
)

message = client.messages.create(
    model="MiniMax-M2.5",
    max_tokens=100,
    messages=[{"role": "user", "content": "你好，请用一句话介绍自己"}]
)

print(message.content[0].text)
EOF

# 运行测试
python test_api.py

如果输出正常，说明 API 配置成功。

三、在 Cursor 中使用 Claude Code

3.1 什么是 Cursor？

Cursor 是一个基于 AI 的代码编辑器，基于 VS Code 构建。它内置了 AI 助手功能，可以与 Claude Code 集成，提供更强大的 AI 编程体验。

3.2 为什么在 Cursor 中使用 Claude Code？

特性	Cursor 默认	Claude Code 集成后
AI 模型	GPT-4 / Claude	可选择 Claude Sonnet 4.6
上下文	当前文件	整个项目 + CLAUDE.md
技能	基础命令	可使用 Skills 扩展
定制化	有限	可配置 CLAUDE.md

3.3 在 Cursor 中配置 Claude Code

步骤一：安装 Cursor

# 使用 Homebrew 安装
brew install --cask cursor

# 或从官网下载
# 访问 https://cursor.sh

步骤二：配置 Claude API

打开 Cursor 设置（Cmd + ,）
切换到「Models」标签
选择「Anthropic」作为 AI Provider
输入你的 Anthropic API Key

或者使用 MiniMax API（国内推荐）：

安装 MiniMax 兼容的 Cursor 插件
配置 API Endpoint 为 https://api.minimax.chat/v1
输入 MiniMax API Key

步骤三：配置 CLAUDE.md

在项目根目录创建 CLAUDE.md：

# 在 Cursor 终端中
touch CLAUDE.md
cat > CLAUDE.md << 'EOF'
# CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

## Project Overview

[填写项目描述]

## Tech Stack

- [技术栈]

## Commands

[常用命令]
EOF

3.4 在 Cursor 中使用 Claude Code

方式一：使用 Cmd+K 快捷键

# 选中代码，按 Cmd+K
# 输入你的问题或指令

方式二：使用 Chat 面板

打开 Cursor 右侧的 Chat 面板（Cmd+L）
选择 Claude 模型
开始对话

方式三：使用 Terminal 集成

在 Cursor 的 Terminal 中直接运行 Claude Code：

# 在 Cursor 终端中
claude

3.5 Cursor + Claude Code 最佳实践

配置项目级上下文

在项目根目录创建 .cursorrules 文件：

# .cursorrules

## 项目概述
[项目描述]

## 技术栈
- [技术栈列表]

## 代码规范
- [规范说明]

## 常用命令
- npm run dev
- npm test

使用 Skills

在 Cursor 中也可以使用 Skills：

# 在 Cursor 终端安装技能
npx skills add anthropic/claude-skills --skill docx --yes
npx skills add intellectronica/agent-skills --skill markdown-converter --yes

3.6 常见问题

检查 API Key 是否正确
检查网络连接
尝试切换不同的 AI 模型

Q2: 上下文不够长

在 CLAUDE.md 中添加更多项目上下文：

## 项目结构

├── src/
│   ├── components/
│   └── utils/
└── tests/

Q3: 如何切换模型

在 Cursor 设置中：

打开 Cmd + ,
选择「Models」
在「Default Model」下拉菜单中选择模型

3.7 相关资源

四、安装文档处理 Skills

4.1 什么是 Skills？

Skills 是 Claude Code 的扩展功能，可以增强特定场景的处理能力。针对文档处理，我们主要安装以下技能：

技能名称	功能
`docx`	读取、编辑、创建 Word 文档
`mermaid-visualizer`	生成 Mermaid 流程图
`prd-generator`	生成产品需求文档 (PRD)
`markdown-converter`	将 PDF/Word/Excel 转换为 Markdown

4.2 安装 skills CLI 工具

首先安装 Claude Code 的 skills 命令行工具：

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

或者使用 Homebrew：

brew install anthropic/claude/claude-skills

4.3 安装文档处理相关 Skills

安装 docx 技能

# 方式一：使用 skills 命令
npx skills add anthropic/claude-skills --skill docx

# 方式二：手动安装
git clone https://github.com/anthropic/claude-skills.git /tmp/claude-skills
cp -r /tmp/claude-skills/skills/docx .claude/skills/

安装 mermaid-visualizer 技能

npx skills add mermaid-js/mermaid-visualizer

安装 prd-generator 技能

npx skills add anthropic/claude-skills --skill prd-generator

安装 markdown-converter 技能

# 安装 intellectronica 的 markdown-converter
npx skills add intellectronica/agent-skills --skill markdown-converter --yes

4.4 验证技能安装

# 查看已安装的技能
ls -la .claude/skills/

# 或使用 skills 命令
claude-skills list

4.5 发现更多 Skills：SkillsClaude 网站

除了上面介绍的文档处理技能，Claude Code 还有大量社区贡献的技能可以使用。

什么是 SkillsClaude？

SkillsClaude 是一个 Claude Code 技能社区，汇集了各种实用的 Claude Code 技能，涵盖了：

分类	示例技能
📝 文档处理	Word、PDF、Excel 转换
🎨 设计工具	Figma、Sketch 设计稿解析
🔍 代码审查	代码质量分析、漏洞检测
📊 数据分析	CSV、JSON 数据处理
🌐 API 调用	HTTP 请求、API 测试
🔧 开发工具	Git、Docker、部署

安装 SkillsClaude 上的技能

# 访问 https://skillsclaude.com 发现更多技能

# 安装方式一：使用 npx skills add
npx skills add [作者名]/[技能名] --yes

# 安装方式二：从 GitHub 仓库安装
git clone https://github.com/[作者名]/[skill-repo].git /tmp/skill
cp -r /tmp/skill .claude/skills/

五、初始化 CLAUDE.md

5.1 什么是 CLAUDE.md？

CLAUDE.md 是 Claude Code 的项目配置文件，放在项目根目录。它告诉 Claude Code：

项目的目录结构
常用的开发命令
项目的技术栈和架构
代码规范和注意事项

5.2 CLAUDE.md 基础模板

# CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

## 项目概述

简要描述项目是什么。

## 目录结构

project/
├── src/ # 源代码
├── tests/ # 测试文件
├── docs/ # 文档
└── README.md # 项目说明


## 技术栈

- 前端：React + TypeScript + Vite
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 开发命令

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm test

代码规范

使用 TypeScript 进行类型检查
组件使用函数式组件 + Hooks
CSS 使用 Tailwind CSS


### 5.3 初始化 CLAUDE.md 的最佳实践

#### 方式一：使用 /init 命令一键生成

Claude Code 提供了 `/init` 命令，可以自动分析项目并生成 CLAUDE.md：

```bash
# 在项目根目录启动 Claude Code
claude

# 输入 /init 命令
/init

/init 命令会：

自动扫描项目目录结构
识别技术栈（Node.js、Python、React 等）
分析 package.json、requirements.txt 等配置文件
生成适合该项目的 CLAUDE.md 配置

让 /init 读取需求文档和项目文件

如果你有 PRD 文档（.docx、.xlsx）或项目文件，可以先将这些文件放在项目目录下，然后运行 /init：

my-project/
├── PRD文档.docx          # PRD 需求文档
├── 需求清单.xlsx         # 需求管理表格
├── src/                  # 源代码
├── CLAUDE.md            # 自动生成
└── README.md

在运行 /init 时，Claude Code 会自动分析这些文件，并在生成的 CLAUDE.md 中包含：

项目概述（来自 README.md）
技术栈（来自 package.json、requirements.txt）
需求文档说明（来自 .docx、.xlsx）
常用命令

最佳实践：组织项目文件

为了让 /init 生成更准确的 CLAUDE.md，建议按以下方式组织项目文件：

project/
├── # 需求文档（会被自动识别）
├── PRD文档.docx
├── 需求清单.xlsx
├── 产品规划.md
│
├── # 项目配置（自动识别技术栈）
├── package.json          # Node.js
├── requirements.txt     # Python
├── pom.xml             # Java
├── go.mod              # Go
│
├── # 源代码
├── src/
├── src-tauri/
│
├── # 文档
├── docs/
├── README.md
│
└── CLAUDE.md           # 自动生成

运行 /init 后，Claude Code 会根据识别的文件类型生成相应的配置章节。

实际示例：需求文档项目的 CLAUDE.md

一个典型的需求文档项目，运行 /init 后可能生成这样的配置：

# CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

## Project Overview

标桥·AI编标产品需求文档仓库，包含 PRD 文档、需求管理表格等。

## Directory Structure

bqpoint/
├── *.docx # PRD 文档
├── *.xlsx # 需求管理表格
├── *.md # Markdown 文档
├── testclaude.py # API 测试脚本
├── CLAUDE.md # 项目指南
└── 个人中心---字数管理/ # React 子项目


## Tech Stack

- Python: python-docx, openpyxl, anthropic
- React: Vite + React + TypeScript

## Commands

```bash
# Python API 测试
python testclaude.py

# React 子项目
cd 个人中心---字数管理 && npm run dev

Requirements Files

此项目包含以下需求文档：

AI快速编标-资信标V2.1.docx
AI编标-我的素材库需求文档.docx
快速编标-需求迭代清单.xlsx


##### /init 的工作原理

`/init` 命令会执行以下操作：

1. **读取目录结构** - 扫描所有文件
2. **识别文件类型** - 区分代码、文档、配置
3. **解析配置文件** - 提取技术栈信息
4. **生成 CLAUDE.md** - 输出结构化配置

```bash
# /init 执行流程示例
# 1. 扫描目录
ls -la                    # 查看所有文件
find . -type f            # 递归列出所有文件

# 2. 识别技术栈
cat package.json          # Node.js 项目
cat requirements.txt       # Python 项目

# 3. 读取需求文档
# 会尝试读取 .docx、.xlsx 等文件
# 并从中提取关键信息

# 4. 生成 CLAUDE.md
# 输出到项目根目录

方式二：手动创建

如果你想更精细地控制 CLAUDE.md 的内容，可以手动创建：

步骤一：分析项目结构

# 查看项目文件
ls -la

# 查看目录树
find . -type f -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" | head -20

步骤二：识别技术栈

# 查看 package.json
cat package.json

# 查看依赖
cat requirements.txt  # Python 项目

步骤三：创建 CLAUDE.md

# 创建基础文件
cat > CLAUDE.md << 'EOF'
# CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

## Project Overview

[填写项目描述]

## Directory Structure

[使用 tree 命令生成结构]

## Tech Stack

- [技术栈列表]

## Commands

```bash
[常用命令]

EOF


### 5.4 进阶：CLAUDE.md 最佳实践

#### 自动生成目录结构

```bash
# 使用 tree 命令生成目录结构
tree -L 3 -I 'node_modules|.git|dist' > CLAUDE.md

包含 .gitignore 文件

确保不提交不必要的文件：

# 在 CLAUDE.md 中添加
## 注意

以下文件不需要提交：
- node_modules/
- .env
- dist/

定期更新

每次项目有重大变更时，记得更新 CLAUDE.md：

新增依赖
修改目录结构
添加新的开发命令

六、完整配置示例

6.1 一键安装脚本

为了方便快速配置，我编写了一个一键安装脚本：

#!/bin/bash

echo "=== Claude Code 完整配置脚本 ==="

# 1. 安装 Claude Code
echo "[1/4] 安装 Claude Code..."
npm install -g @anthropic-ai/claude-code

# 2. 安装 skills CLI
echo "[2/4] 安装 skills CLI..."
npm install -g @anthropic-ai/claude-skills

# 3. 安装文档处理技能
echo "[3/4] 安装文档处理技能..."
npx skills add anthropic/claude-skills --skill docx --yes
npx skills add anthropic/claude-skills --skill prd-generator --yes
npx skills add intellectronica/agent-skills --skill markdown-converter --yes

# 4. 创建 CLAUDE.md
echo "[4/4] 创建 CLAUDE.md..."
cat > CLAUDE.md << 'EOF'
# CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

## Project Overview

[请填写项目描述]

## Directory Structure

[请使用 tree 命令生成]

## Tech Stack

[请填写技术栈]

## Commands

[请填写常用命令]
EOF

echo ""
echo "=== 配置完成！ ==="
echo ""
echo "下一步："
echo "1. 配置 MiniMax API Key"
echo "2. 根据项目实际情况编辑 CLAUDE.md"
echo "3. 运行 claude 开始使用"

6.2 验证配置

所有配置完成后，运行以下命令验证：

# 验证 Claude Code
claude --version

# 验证技能
ls -la .claude/skills/

# 验证 Python 环境
python test_api.py

6.3 常见问题

Q1: 安装时提示权限错误

# 使用 sudo 权限安装
sudo npm install -g @anthropic-ai/claude-code

Q2: MiniMax API 调用失败

检查 API Key 是否正确
检查网络连接
确认 API 余额充足

Q3: Skills 安装失败

# 清除缓存后重试
rm -rf ~/.npm/_npx
npx skills add [skill-name] --yes

Q4: CLAUDE.md 不生效

确保文件名为 CLAUDE.md（全大写），放在项目根目录。

七、总结

本文详细介绍了：

安装 Claude Code - 通过 npm 或 Homebrew 安装
配置 MiniMax API - 获取 API Key 并配置环境变量
安装文档处理 Skills - docx、mermaid、prd-generator、markdown-converter
初始化 CLAUDE.md - 使用 /init 一键生成或手动创建

八、进阶技巧

8.1 在 /init 后优化 CLAUDE.md

/init 生成的 CLAUDE.md 是基础版本，你可以在此基础上添加更多细节：

# 添加项目特定信息

## 核心功能模块

### 1. 资信标
- AI 解析招标文件
- 企业资质管理

### 2. 技术标
- AI 生成目录
- 自动内容生成

## PRD 文档说明

- 所有 PRD 必须使用中文编写
- 包含 Mermaid 流程图
- 版本格式：V1.0, V1.1, V2.1

8.2 使用 Skill 处理文档

安装技能后，可以直接用命令处理文档：

# 读取 Word 文档
/docx 读取 PRD文档.docx

# 生成 Mermaid 流程图
/mermaid-visualizer

# 生成 PRD 文档
/prd-generator

# 转换文档格式
uvx markitdown 文档.pdf -o 文档.md

完成以上步骤后，你就可以开始使用 Claude Code 进行高效的文档处理和开发工作了！

参考资源

本文会持续更新，如有疑问欢迎评论区交流。