Claude Code 使用手册

Claude Code 使用手册

📖 目录

• 简介
• 系统要求
• 安装与配置
  • 安装依赖
  • 创建配置文件
  • 配置说明
• 实际使用
  • 启动服务
  • 命令行使用
  • VS Code 集成
  • 动态切换模型
• 常用命令参考
• 高级功能
• 常见问题
• 最佳实践

---

简介

Claude Code Router 是一个强大的 AI 模型路由工具，可以与 Claude Code 配合使用，实现：

• ✅ 多模型支持：在同一界面中使用多个 AI 模型（Claude、DeepSeek、Gemini 等）
• ✅ 成本优化：根据任务复杂度自动选择合适的模型，降低使用成本
• ✅ 灵活切换：实时切换模型，无需重启服务
• ✅ 多场景适配：支持命令行、VS Code 插件、自动化脚本等多种使用场景

---

系统要求

• Node.js：v16.0 或更高版本
• 操作系统：Windows / macOS / Linux
• 网络：能够访问所配置的 AI 模型 API

---

安装与配置

安装依赖

打开终端，执行以下命令安装所需工具：

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code# 安装 Claude Code Router
npm install -g @musistudio/claude-code-router

验证安装：

# 检查 Claude Code 版本
claude-code --version# 检查 Claude Code Router 版本
ccr --version

---

创建配置文件

首次使用需要创建配置目录和配置文件：

Linux / macOS：

mkdir -p ~/.claude-code-router
nano ~/.claude-code-router/config.json

Windows (PowerShell)：

mkdir -Force $env:USERPROFILE\.claude-code-router
notepad $env:USERPROFILE\.claude-code-router\config.json

---

配置说明

在 config.json 中写入以下配置（根据实际需求修改）：

{"APIKEY": "your-secret-key","LOG": true,"Providers": [{"name": "deepseek","api_base_url": "https://api.deepseek.com/chat/completions","api_key": "sk-your-deepseek-key","models": ["deepseek-chat", "deepseek-reasoner"],"transformer": { "use": ["deepseek"] }},{"name": "openrouter","api_base_url": "https://openrouter.ai/api/v1/chat/completions","api_key": "sk-your-openrouter-key","models": ["anthropic/claude-3.5-sonnet"],"transformer": { "use": ["openrouter"] }},{"name": "ollama","api_base_url": "http://localhost:11434/v1/chat/completions","api_key": "ollama","models": ["qwen2.5-coder:32b"],"transformer": { "use": ["ollama"] }}],"Router": {"default": "deepseek,deepseek-chat","think": "deepseek,deepseek-reasoner","longContext": "openrouter,anthropic/claude-3.5-sonnet","local": "ollama,qwen2.5-coder:32b"}
}

配置项说明

配置项	说明	示例
APIKEY	Router 服务的访问密钥	"your-secret-key"
LOG	是否开启日志记录	true / false
Providers	模型提供商列表	见下方说明
Router	路由策略配置	定义不同场景使用的模型

Provider 配置说明

每个 Provider 包含以下字段：

• name：提供商名称（自定义）
• api_base_url：API 基础 URL
• api_key：API 密钥
• models：支持的模型列表
• transformer：请求转换器配置

Router 路由策略

你可以为不同的任务场景配置默认模型：

• default：日常任务（性价比优先）
• think：复杂推理任务（推理能力优先）
• longContext：长文本处理（上下文窗口优先）
• local：本地模型（隐私优先）

---

实际使用

启动服务

方式一：启动 Claude Code（推荐）

ccr code

此命令会：

1. 启动 Claude Code Router 服务
2. 自动打开 Claude Code 交互式客户端
3. 所有模型请求通过 Router 转发

方式二：仅启动 Router 服务

ccr start

适用于需要长期后台运行的场景（如 VS Code 集成）。

方式三：启动 Web 配置界面

ccr ui

在浏览器中管理配置和查看日志。

---

命令行使用

交互式对话

ccr code

进入交互模式后，直接输入问题即可：

> 请解释快速排序算法
> 帮我写一个 Python 爬虫示例
> 优化这段代码：[粘贴代码]

非交互式调用

# 单次问答
ccr code "解释什么是 Docker"# 适合脚本自动化
ccr code "分析这个日志文件的错误" < error.log

---

VS Code 集成

步骤一：安装 VS Code 插件

在 VS Code 中搜索并安装：Claude Code for VS Code

步骤二：配置项目

在项目根目录下创建 .claude/settings.json 文件：

{"env": {"ANTHROPIC_BASE_URL": "http://localhost:3456","ANTHROPIC_API_KEY": "your-secret-key"}
}

注意：ANTHROPIC_API_KEY 需要与 config.json 中的 APIKEY 保持一致。

步骤三：启动服务

ccr start

步骤四：使用插件

1. 在 VS Code 左侧点击 Claude Code 图标
2. 选择代码后右键，选择 “Ask Claude” 或 “Refactor with Claude”
3. 在侧边栏中与 Claude 交互

---

动态切换模型

在交互式命令行或 VS Code 中，使用以下命令切换模型：

/model openrouter,anthropic/claude-3.5-sonnet

格式：/model provider,model-name

示例：

# 切换到 DeepSeek
/model deepseek,deepseek-chat# 切换到本地 Ollama 模型
/model ollama,qwen2.5-coder:32b# 切换到推理模型
/model deepseek,deepseek-reasoner

---

常用命令参考

命令	功能	使用场景
ccr code	启动 Claude Code（带路由）	交互式对话
ccr start	启动 Router 服务（后台）	VS Code 集成
ccr ui	启动 Web 配置界面	管理配置和查看日志
ccr stop	停止 Router 服务	结束服务
ccr status	查看服务状态	检查运行状态
ccr code "问题"	命令行直接调用	脚本自动化
/model provider,model	切换模型	交互式会话中
/help	查看帮助信息	查看可用命令
/exit	退出交互模式	结束会话

---

高级功能

自动路由策略

根据问题类型自动选择合适的模型：

{"Router": {"default": "deepseek,deepseek-chat","patterns": {"code": "deepseek,deepseek-chat","translate": "openrouter,anthropic/claude-3.5-sonnet","math": "deepseek,deepseek-reasoner"}}
}

成本统计

查看 API 调用成本统计：

ccr stats

日志查看

查看详细的请求日志：

# Linux / macOS
tail -f ~/.claude-code-router/logs/router.log# Windows
Get-Content -Tail 50 -Wait $env:USERPROFILE\.claude-code-router\logs\router.log

CI/CD 集成

在 GitHub Actions 中使用：

- name: Setup Claude Code Routerrun: |npm install -g @musistudio/claude-code-routerccr start- name: Run AI Code Reviewrun: |ccr code "Review this code: $(cat src/main.py)"

---

常见问题

Q1: 安装后提示 command not found

解决方案：

• 确保 Node.js 全局模块路径在 PATH 环境变量中
• 尝试重新打开终端或执行 source ~/.bashrc

Q2: 连接模型 API 失败

检查项：

1. API Key 是否正确
2. 网络连接是否正常
3. API 端点 URL 是否正确
4. 是否需要代理设置

Q3: VS Code 插件无法连接

解决方案：

1. 确认 ccr start 服务已启动
2. 检查 .claude/settings.json 配置是否正确
3. 确认端口 3456 未被占用

Q4: 模型响应速度慢

优化建议：

• 使用本地模型（Ollama）处理简单任务
• 切换到响应更快的模型提供商
• 检查网络延迟

Q5: 如何保护 API Key 安全

最佳实践：

• 将 config.json 设置为只读（chmod 600）
• 不要将配置文件提交到 Git 仓库
• 使用环境变量存储敏感信息

---

最佳实践

1. 成本优化策略

日常任务 → DeepSeek（低成本）
复杂推理 → DeepSeek Reasoner（中等成本）
代码生成 → 本地 Ollama（免费）
关键任务 → Claude 3.5 Sonnet（高质量）

2. 模型选择建议

任务类型	推荐模型	理由
代码补全	DeepSeek Chat	速度快、成本低
代码重构	Claude 3.5 Sonnet	理解能力强
数学推理	DeepSeek Reasoner	推理能力出色
文本翻译	Claude 3.5 Sonnet	语言能力强
快速问答	本地 Ollama	响应快、免费

3. 工作流建议

1. 开发阶段：使用本地模型或低成本模型快速迭代
2. 测试阶段：切换到高性能模型进行代码审查
3. 生产部署：使用稳定的 API 模型确保可靠性

4. 配置模板

个人开发者（成本优先）：

{"Router": {"default": "ollama,qwen2.5-coder:32b","complex": "deepseek,deepseek-reasoner"}
}

团队协作（性能优先）：

{"Router": {"default": "openrouter,anthropic/claude-3.5-sonnet","think": "deepseek,deepseek-reasoner"}
}

---

附录

支持的模型提供商

• Anthropic Claude（通过 OpenRouter）
• DeepSeek
• OpenAI（通过 OpenRouter）
• Google Gemini
• 火山引擎
• Ollama（本地模型）
• Groq
• Together AI

相关资源

• Claude Code 官方文档
• Claude Code Router GitHub
• DeepSeek API 文档
• OpenRouter 文档

更新日志

• v1.0.0（2025-01）：初始版本，支持基本路由功能
• v1.1.0（2025-03）：新增自动路由策略
• v1.2.0（2025-10）：支持 VS Code 深度集成

---

许可与贡献

本使用手册基于实际使用经验编写，欢迎提出改进建议。

编写时间：2025年10月
最后更新：2025年10月17日

---

💡 提示：如果你在使用过程中遇到问题，可以通过以下方式获取帮助：

1. 查看详细日志：ccr logs
2. 访问 Web 配置界面：ccr ui
3. 查看官方文档和社区讨论
4. 提交 Issue 到 GitHub 仓库

祝你使用愉快！🚀