Mac 用户 Claude Code 完全配置指南：接入 DeepSeek / Kimi 等国内大模型

[!abstract] 适用环境与目标

• 适用环境：macOS（Intel / Apple Silicon）+ Homebrew + zsh
• 目标：在无法直接访问 Anthropic 官方服务的环境下，让 Claude Code 通过国内大模型（DeepSeek、Kimi、GLM、MiniMax 等）正常运行。

一、安装 Claude Code

Claude Code 是 Anthropic 推出的终端 AI 编程助手，可通过 Homebrew 一键安装：

brew install --cask claude-code@latest

安装完成后，终端输入：

claude

如果看到 Claude Code 的 ASCII 艺术启动画面，说明安装成功。

二、国内网络环境下的核心问题

安装完成后，直接运行 claude 大概率会报错：

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

原因：Claude Code 默认直连 Anthropic 官方 API（api.anthropic.com），而国内网络环境无法稳定访问该地址。

解决思路：Claude Code 底层调用的是 Anthropic Messages API。国内大模型厂商（DeepSeek、Kimi、GLM、MiniMax 等）已经提供了兼容该协议的接口。我们只需修改几个环境变量，让 Claude Code 把请求转发到国内模型即可。

三、方案探索：ccswitch 工具（及踩坑记录）

社区有一个专门用于 Claude Code 模型切换的开源工具 claude-code-switch（简称 ccswitch），理论上可以一键切换模型。

3.1 尝试安装 ccswitch

npm install -g claude-code-switch

踩坑 1：权限报错（EACCES）

npm error code EACCES
npm error syscall symlink
npm error path ../lib/node_modules/claude-code-switch/bin/ccs.js
npm error dest /usr/local/bin/ccs

原因：macOS 的 /usr/local/bin 默认需要 root 权限写入，npm -g 全局安装时无法创建符号链接。

[!warning] 不建议使用 sudo npm install -g
npm 包的 postinstall 脚本会以 root 权限执行任意代码，存在供应链攻击风险。更安全的做法是将全局包安装到用户目录，或直接使用 npx。

3.2 改用 npx 运行（无需安装）

npx claude-code-switch deepseek

踩坑 2：切换后无输出 / 环境变量未生效

npx claude-code-switch status
# （没有任何输出）

echo $ANTHROPIC_BASE_URL
# （空）

原因：~/.ccswitch/models.json 配置文件不存在，ccswitch 找不到 API Key，导致切换命令实际上没有生效。

3.3 创建 ccswitch 配置文件

mkdir -p ~/.ccswitch
cat > ~/.ccswitch/models.json << 'EOF'
{
  "deepseek": {
    "base_url": "https://api.deepseek.com/anthropic",
    "api_key": "sk-你的DeepSeekKey",
    "model": "deepseek-chat"
  },
  "kimi": {
    "base_url": "https://api.moonshot.cn/anthropic",
    "api_key": "sk-你的KimiKey",
    "model": "kimi-k2-thinking-turbo"
  }
}
EOF

踩坑 3：填好 Key 后仍然无效

即使配置文件存在且 Key 正确，npx claude-code-switch deepseek 执行后仍然没有任何反馈，echo $ANTHROPIC_BASE_URL 依然为空。

结论：ccswitch 工具在当前版本（0.0.7）下存在稳定性问题，不建议作为主要生产工具。我们转而使用更直接、更可靠的手动环境变量配置方案。

四、最终推荐方案：手动配置环境变量

这是最透明、最稳定的方式，没有中间工具，出了问题一眼就能看出来。

4.1 获取 API Key

注册后进入「API Keys」页面，创建并复制 Key。

4.2 在当前终端手动设置（临时生效）

把 sk-你的DeepSeekKey 替换为真实 Key，在当前终端执行：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-你的DeepSeekKey"
export ANTHROPIC_MODEL="deepseek-chat"

验证是否生效：

echo $ANTHROPIC_BASE_URL
# 输出：https://api.deepseek.com/anthropic

启动 Claude Code：

claude

如果左下角显示 deepseek-v4-pro（或类似的 DeepSeek 模型标识），说明配置成功。

五、长期化配置：写入 ~/.zshrc

上面的 export 只对当前终端窗口有效，关闭后失效。为了方便长期使用，我们将配置写入 ~/.zshrc。

5.1 编辑 ~/.zshrc

open -e ~/.zshrc
# 或者使用 VS Code：code ~/.zshrc

在文件末尾追加以下内容（务必将 sk-... 替换为你的真实 API Key）：

# ============================================
# Claude Code 国内大模型切换配置
# ============================================

# DeepSeek 配置
cc-ds() {
  export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
  export ANTHROPIC_AUTH_TOKEN="sk-你的DeepSeekKey"
  export ANTHROPIC_MODEL="deepseek-chat"
  echo "✅ 已切换至 DeepSeek"
}

# Kimi 配置
cc-kimi() {
  export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic"
  export ANTHROPIC_AUTH_TOKEN="sk-你的KimiKey"
  export ANTHROPIC_MODEL="kimi-k2-thinking-turbo"
  echo "✅ 已切换至 Kimi"
}

# GLM 配置（可选）
cc-glm() {
  export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"
  export ANTHROPIC_AUTH_TOKEN="sk-你的GLMKey"
  export ANTHROPIC_MODEL="glm-4-7"
  echo "✅ 已切换至 GLM"
}

# 恢复官方 Claude
cc-official() {
  unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL
  echo "✅ 已恢复官方 Claude"
}

# 快捷启动命令
ccd() { cc-ds; claude "$@"; }
cck() { cc-kimi; claude "$@"; }
ccg() { cc-glm; claude "$@"; }

5.2 重新加载配置

source ~/.zshrc

六、日常使用速查表

配置完成后，以下是常用的快捷命令：

6.1 验证当前使用的模型

在 Claude Code 运行界面，左下角会显示当前模型名称，例如：

deepseek-v4-pro · API Usage Billing

或者在终端执行：

echo $ANTHROPIC_MODEL

七、主流模型配置参数速查

八、常见问题

Q1：Claude Code 启动后仍然显示 "Unable to connect to Anthropic services"

排查步骤：

1. 检查环境变量是否生效：echo $ANTHROPIC_BASE_URL
2. 如果为空，说明当前终端没有正确加载配置，重新执行 source ~/.zshrc
3. 检查 API Key 是否正确（Key 错误会导致认证失败）
4. 检查网络是否能访问对应平台（如 curl https://api.deepseek.com）

Q2：新开的终端窗口需要重新设置环境变量吗？

答：如果已经按照第五节写入了 ~/.zshrc，并且执行过 source ~/.zshrc，则新终端会自动继承配置。但环境变量不会自动切换模型，需要手动执行 cc-ds 或直接使用 ccd 启动。

Q3：如何让 Claude Code 默认使用国内模型，而不是每次手动切换？

答：在 ~/.zshrc 中直接写入 export 语句（而不是函数），这样每次打开终端就自动生效：

# 默认使用 DeepSeek
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-你的DeepSeekKey"
export ANTHROPIC_MODEL="deepseek-chat"

Q4：API 调用费用如何？

答：各平台都有免费额度，DeepSeek 和 GLM 的免费额度相对 generous。具体费率请查看各平台的官方定价页面。Claude Code 作为编程助手，代码补全和文件操作的 Token 消耗量通常不大。

八、Claude Code 入门：常用命令与实战案例

配置好模型只是第一步，下面介绍 Claude Code 的核心用法，帮助你快速上手这个终端 AI 编程助手。

8.1 启动方式

Claude Code 有两种启动方式：

[!tip] 最佳实践
进入你的项目目录后再启动 Claude Code，这样它能自动识别项目结构、技术栈和依赖关系。

cd ~/my-project
ccd  # 或 cck，取决于你配置的快捷命令

8.2 内置命令（以 / 开头）

在 Claude Code 交互界面中，输入 ? 可查看所有快捷命令。以下是核心命令：

使用示例

> /review
Claude 会分析你当前打开的文件，指出：
- 潜在的逻辑错误
- 性能优化建议
- 代码风格问题
- 安全风险

8.3 日常交互模式

Claude Code 的核心使用方式是自然语言对话。你可以像和同事交流一样描述需求。

场景 1：代码生成

> 帮我写一个 Python 函数，读取 CSV 文件并返回按日期排序的 DataFrame

Claude 会：
1. 询问 CSV 的日期列名（或根据上下文推断）
2. 生成带类型注解和文档字符串的函数
3. 询问是否需要处理异常（如文件不存在、日期格式错误）
4. 将代码写入你指定的文件

场景 2：代码重构

> 把 src/utils.py 里的重复逻辑提取成独立函数

Claude 会：
1. 读取 src/utils.py
2. 识别重复代码块
3. 提出重构方案（展示 diff）
4. 经你确认后执行修改

场景 3：Debug 调试

> 运行项目测试时报错了，帮我看看

Claude 会：
1. 执行测试命令（如 pytest / npm test）
2. 分析错误堆栈
3. 定位问题根源
4. 提出修复方案或自动修复

场景 4：批量文件操作

> 把所有 .js 文件里的 console.log 替换成 logger.debug

Claude 会：
1. 搜索项目中的所有 .js 文件
2. 展示将要修改的文件列表
3. 经确认后执行批量替换
4. 生成变更摘要

8.4 文件与代码操作

Claude Code 可以直接操作文件系统，所有修改都会征求你的确认。

读取文件

> 看一下 src/App.tsx 的内容
> 比较 src/old.js 和 src/new.js 的区别
> 搜索项目中所有用到 useEffect 的地方

创建文件

> 创建一个 Dockerfile，基于 Node 18 镜像，暴露 3000 端口
> 在 tests/ 目录下添加 login.spec.js 的 Playwright 测试

编辑文件

> 在 README.md 的安装章节后面添加 Troubleshooting 部分
> 给 src/api.js 里的 fetchUser 函数添加重试逻辑
> 删除 src/components/OldComponent.jsx（已废弃）

运行终端命令

Claude Code 可以代表你运行终端命令，执行前会请求确认：

> 安装 axios 和 lodash
Claude: 我将运行 `npm install axios lodash`，是否继续？ (Y/n)

> 把当前分支推送到远程
Claude: 我将运行 `git push origin feature-branch`，是否继续？ (Y/n)

8.5 项目初始化：CLAUDE.md

/init 命令会在项目根目录创建一个 CLAUDE.md 文件，这是给 Claude 的"项目说明书"。

CLAUDE.md 的作用：

• 描述项目架构和技术栈
• 定义编码规范（缩进、命名约定、注释风格）
• 指定测试策略和目录结构
• 列出需要特别注意的业务逻辑

示例 CLAUDE.md：

# 项目规范

## 技术栈
- React 18 + TypeScript
- Vite 构建工具
- Tailwind CSS
- React Query 管理服务端状态

## 编码规范
- 使用函数组件 + Hooks
- 类型定义放在 `src/types/` 目录
- API 请求统一封装在 `src/api/` 目录
- 组件 props 必须写接口定义

## 测试要求
- 新增功能必须配套单元测试
- 使用 Vitest + React Testing Library
- 测试文件放在 `__tests__/` 目录或 `.test.ts` 后缀

创建后，Claude 在后续对话中会自动遵循这些规范，无需每次重复说明。

8.6 实战完整案例

案例：从零搭建一个 Express API 项目

步骤 1：创建项目目录并进入

mkdir my-api && cd my-api
ccd

步骤 2：初始化项目

> 初始化一个 Node.js Express 项目，使用 TypeScript，添加 eslint 和 prettier 配置

Claude 会：

1. 运行 npm init -y
2. 安装 express、typescript、@types/express、eslint、prettier 等依赖
3. 创建 tsconfig.json
4. 创建 .eslintrc.js 和 .prettierrc
5. 创建 src/index.ts 入口文件

步骤 3：创建用户模块

> 创建用户相关的 CRUD API，包括：
> - GET /users 获取用户列表
> - GET /users/:id 获取单个用户
> - POST /users 创建用户
> - PUT /users/:id 更新用户
> - DELETE /users/:id 删除用户
> 
> 使用内存数组存储数据即可，先不做数据库

Claude 会：

1. 创建 src/routes/users.ts
2. 创建 src/types/user.ts 定义 User 接口
3. 在 src/index.ts 中注册路由
4. 添加基本的输入验证

步骤 4：添加测试

> 给用户模块添加 Jest 单元测试，覆盖所有路由

Claude 会：

1. 安装 jest、supertest、@types/jest
2. 创建 src/routes/users.test.ts
3. 配置 jest.config.js

步骤 5：代码审查

> /review

Claude 会检查代码中的潜在问题，比如：

• 缺少错误处理中间件
• 没有输入校验
• TypeScript 类型不够严谨

步骤 6：提交代码

> /commit

Claude 会自动：

1. git add .
2. 生成规范的 commit message（如 feat: add user CRUD endpoints with tests）
3. git commit

8.7 快捷键与效率技巧

效率技巧

1. 多轮对话保持上下文：Claude Code 会记住整个会话的历史，你可以随时说"刚才那个函数再改一下"或"回到上一步"。

2. @ 引用文件：在对话中用 @文件名 快速让 Claude 关注特定文件。

   > @src/utils.js 里的 parseDate 函数有 bug，帮我修复

3. 批量确认：Claude 在执行危险操作（如删除文件、git push）前会征求确认。你可以输入 Y 确认单条，A 确认全部剩余操作，N 跳过，Q 退出。

4. 查看成本：随时输入 /cost 了解当前会话消耗了多少 Token，便于控制预算。

5. 结合 tmux/screen：在 tmux 会话中运行 Claude Code，即使关闭终端也不会中断长任务。

8.8 使用注意事项

九、Skills 系统详解：扩展 Claude Code 的能力边界

Claude Code 的 Skills 系统是其最强大的特性之一。通过 Skills，你可以为 Claude 注入特定领域的知识、编码规范、团队约定，甚至自定义命令。本节将详细讲解 Skills 的安装、作用范围，以及国内网络环境下的最佳实践。

9.1 Skills 是什么

简单来说，Skill 是一个包含 SKILL.md 文件的文件夹，里面写满了给 Claude 的「专项 Instructions」。安装后，Claude 在对应场景下会自动调用这些知识。

类比理解：

• 如果把 Claude Code 比作一个通用程序员
• 那么 Skills 就是他的「专业资格证书」——装上 React Skill，他就是一个熟手 React 开发者；装上 Testing Skill，他就精通各种测试框架

典型使用场景：

• 团队编码规范（缩进、命名、注释风格）
• 特定技术栈的深度知识（Next.js、Django、Rust 等）
• 内部工具链的使用方法（私有 npm 仓库、内部 CLI）
• 代码审查标准（安全规范、性能要求）

9.2 Skills 的两种作用范围

这是最容易混淆的地方。Claude Code 的 Skills 同时支持全局和项目级两种作用范围，优先级规则是：项目级 > 全局。

全局 Skills（用户级）

示例：你个人习惯使用 2 空格缩进、单引号、尾部逗号，可以把这些偏好写入一个全局 Skill，这样每个项目都会自动遵循。

项目级 Skills（局部，默认）

示例：公司 A 项目使用 Vue + Pinia + Element Plus，有一套特定的组件封装规范。把这些写入项目级 Skill，提交到 Git 仓库，团队所有人都能获得一致的 AI 辅助体验。

优先级规则

当全局和项目级存在同名 Skill 时，项目级优先。这意味着：

• 你可以有一个全局的「通用代码规范」Skill
• 同时在某个项目中放置「该项目特定的规范」Skill
• Claude 会优先遵循项目级的约定

9.3 安装 Skills 的两种方式

方式一：插件市场安装（推荐，网络通畅时）

Claude Code 内置了插件市场体系，类似于 npm 的包管理。

核心命令：

# 查看已添加的市场
/plugin marketplace list

# 添加市场（必须使用 HTTPS 地址）
/plugin marketplace add https://github.com/anthropics/claude-plugins-official

# 浏览市场可用插件
/plugin marketplace list

# 安装插件（格式：插件名@市场名）
/plugin install code-review@claude-plugins-official

# 查看已安装插件
/plugin list

# 启用/禁用插件
/plugin enable 插件名@市场名
/plugin disable 插件名@市场名

# 卸载插件
/plugin uninstall 插件名@市场名

⚠️ 重要注意：/plugin install 默认安装到项目级（./.claude/skills/），不是全局的。这意味着：

• 你在项目 A 安装了 Skill
• 进入项目 B 后，该 Skill 不可用

如果你想让所有项目都能用，安装后需要手动复制到全局目录：

# 从项目级复制到全局（macOS/Linux）
cp -r ./.claude/skills/skill-name ~/.claude/skills/

方式二：本地手动安装（离线环境、国内网络受限时）

如果网络不畅或处于离线环境，可以直接将 Skill 文件夹复制到指定目录。

步骤 1：获取 Skill 文件

从 GitHub 下载 Skill 仓库的 ZIP 包，解压后得到 Skill 文件夹（内部应包含 SKILL.md 文件）。

步骤 2：复制到目标目录

# 全局安装（所有项目可用）
cp -r /path/to/skill-folder ~/.claude/skills/

# 项目级安装（仅当前项目可用）
mkdir -p ./.claude/skills
cp -r /path/to/skill-folder ./.claude/skills/

步骤 3：验证安装

重启 Claude Code，然后询问：

> 你有哪些可用的 Skills？

如果 Claude 列出了你刚安装的 Skill，说明安装成功。

9.4 国内网络环境下的 Skills 安装策略

国内用户安装 Skills 时，最常见的问题是访问 GitHub 慢或超时。以下是几种经过验证的解决方案：

策略 1：配置 Git 代理（推荐）

如果你已经有代理工具（Clash、Surge、V2Ray 等），配置 Git 走代理：

# HTTP 代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# SOCKS5 代理（部分工具使用）
git config --global http.proxy socks5://127.0.0.1:7890

[!info] 端口说明
端口号 7890 请替换为你实际代理工具的 HTTP/SOCKS5 端口（Clash 默认 7890，Surge 默认 6152）。

配置后，/plugin marketplace add 和 /plugin install 命令就可以正常访问 GitHub 了。

策略 2：使用 GitHub 镜像站

如果不想配置代理，可以使用国内的 GitHub 镜像站：

# 添加市场时使用镜像地址
/plugin marketplace add https://gh.api.99988866.xyz/https://github.com/anthropics/claude-plugins-official

常用镜像前缀：

• https://gh.api.99988866.xyz/https://github.com/...
• https://mirror.ghproxy.com/https://github.com/...
• https://ghps.cc/https://github.com/...

[!warning] 镜像站稳定性说明
镜像站稳定性不一，如果某个失效，尝试换一个。

策略 3：完全离线安装（内网/无网络环境）

这是最稳妥的方案，适合公司内网或完全无法访问外网的环境。

步骤 1：在能上网的机器上下载 Skills

访问 Claude Code 官方插件仓库或社区仓库，下载 ZIP 包：

• 官方市场：https://github.com/anthropics/claude-plugins-official
• 社区市场：搜索 claude code skills github

步骤 2：传输到目标机器

通过 U 盘、内网文件服务器、企业微信/钉钉等方式，将解压后的 Skill 文件夹传输到目标 macOS 机器。

步骤 3：手动安装

# 创建全局 skills 目录
mkdir -p ~/.claude/skills

# 复制 Skill 文件夹（假设传输到了 ~/Downloads/skills/）
cp -r ~/Downloads/skills/* ~/.claude/skills/

# 验证目录结构
ls -la ~/.claude/skills/
# 应该看到各个 Skill 文件夹，每个文件夹内有 SKILL.md

步骤 4：重启 Claude Code 并使用

ccd

> 你有哪些可用的 Skills？
> /skill-name  # 调用特定 Skill

9.5 热门 Skills 推荐

以下是社区中评价较高的 Skills，供参考：

安装方法示例：

/plugin install code-review@claude-plugins-official
/plugin install testing@claude-plugins-official

9.6 自定义自己的 Skill

如果现成的 Skills 不能满足需求，你可以自己写一个。

步骤 1：创建 Skill 目录和文件

mkdir -p ~/.claude/skills/my-team-rules
cat > ~/.claude/skills/my-team-rules/SKILL.md << 'EOF'
# My Team Coding Rules

## 命名规范
- 变量/函数：camelCase
- 组件/类：PascalCase
- 常量：UPPER_SNAKE_CASE
- 私有属性：_前缀

## 代码风格
- 缩进：2 个空格
- 引号：单引号
- 分号：必须
- 行尾逗号：多行时必须

## 文件组织
- 组件放在 `src/components/`
- 工具函数放在 `src/utils/`
- API 封装放在 `src/api/`
- 类型定义放在 `src/types/`

## 提交规范
- feat: 新功能
- fix: 修复
- docs: 文档
- style: 格式
- refactor: 重构
- test: 测试
- chore: 构建/工具
EOF

步骤 2：重启 Claude Code 即可生效

现在当你让 Claude 写代码时，他会自动遵循你定义的规范。

9.7 Skills 使用注意事项

写在最后

Claude Code 的核心价值在于把 AI 能力无缝嵌入到终端工作流中。它不是一个简单的聊天机器人，而是能读懂你的代码、操作你的文件系统、运行你的测试、提交你的代码的"编程搭档"。

通过 Skills 系统，你可以进一步定制这个搭档的专业能力——无论是团队的编码规范、特定技术栈的深度知识，还是个人的开发偏好，都能通过 Skills 注入到 Claude 中，让它真正成为"懂你的 AI"。

配合 DeepSeek 或 Kimi 等国内模型，即使在不方便访问 Anthropic 官方服务的环境下，你也能获得流畅且高度个性化的 AI 编程体验。

建议从一个小功能或一次代码重构开始尝试，逐步熟悉它的交互模式。你会发现，很多原本需要查文档、写样板代码、反复调试的工作，现在只需几句话就能完成。

祝你编码愉快！

十、总结

本文记录了在 macOS 上安装和配置 Claude Code 的完整过程，重点解决了国内网络环境下无法连接 Anthropic 官方服务的问题。

核心要点：

• Claude Code 通过 Anthropic Messages API 通信，国内模型提供了兼容接口
• 修改 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL 三个环境变量即可切换
• ccswitch 工具目前不够稳定，推荐直接手动配置 + 写入 ~/.zshrc
• 使用 npx 或用户级 npm 全局目录，避免 sudo npm install -g 的安全风险

现在，输入 ccd 或 cck，开始你的 AI 编程之旅吧。

参考链接

• Claude Code 官方文档：https://docs.anthropic.com/en/docs/claude-code/overview
• DeepSeek API 平台：https://platform.deepseek.com
• Kimi API 平台：https://platform.moonshot.cn
• ccswitch 项目：https://github.com/yourccswitch/claude-code-switch