1. 项目概述
在WSL环境中配置Claude Code并通过Router中间件将请求转发到DeepSeek模型,是一个典型的AI工具链整合案例。这个方案的核心价值在于:让用户能够继续使用熟悉的Claude Code交互界面,同时将实际的计算请求路由到DeepSeek模型,从而获得更灵活、更经济的AI辅助体验。
我最近在自己的开发环境中完整实施了这套方案,过程中遇到了不少"坑",也积累了一些实战经验。本文将详细记录从环境准备到问题排查的全过程,特别会重点讲解那些官方文档没有明确说明,但实际使用中又至关重要的细节。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与基础安装
2.1 WSL环境确认
首先需要确保WSL环境正常工作。我使用的是Ubuntu 22.04 LTS发行版,这是目前最稳定的选择。在Windows终端中输入:
bash复制wsl --list --verbose
确认你的WSL版本为2(WSL 1会有性能问题)。如果显示为版本1,可以通过以下命令升级:
bash复制wsl --set-version Ubuntu-22.04 2
注意:WSL 2需要启用Windows的虚拟化功能。如果遇到问题,需进入BIOS启用Intel VT-x或AMD-V技术。
2.2 Claude Code安装细节
官方提供的安装命令确实简单:
bash复制curl -fsSL https://claude.ai/install.sh | bash
但实际执行时我发现几个关键点:
- 安装脚本会尝试创建/usr/local/bin/claude的符号链接,如果该位置已有文件,安装会静默失败。建议先检查:
bash复制ls -la /usr/local/bin/claude
- 安装完成后,建议立即验证版本:
bash复制claude --version
如果报"command not found",可能是PATH环境变量问题。WSL的PATH有时会被Windows的PATH污染,解决方法:
bash复制export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
source ~/.bashrc
3. Node.js与Router安装
3.1 Node.js安装避坑指南
官方文档建议使用Nodesource的安装脚本,但有几个细节需要注意:
bash复制curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
-
确保使用-E参数保留当前用户的环境变量,否则sudo可能会丢失必要的代理设置(如果你在公司网络)。
-
安装完成后,验证node和npm的路径:
bash复制which node
which npm
这两个命令应该都返回/usr/bin/下的路径。如果显示Windows路径(如/mnt/c/Program Files/nodejs),说明PATH设置有误。
3.2 Router安装的特殊处理
全局安装Router时:
bash复制npm install -g @musistudio/claude-code-router
常见问题及解决:
- EACCES权限错误:这是因为npm默认尝试写入系统目录。有两种解决方案:
- 使用sudo(不推荐)
- 更好的方法是重新配置npm的全局安装目录:
bash复制mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
- 安装后ccr命令不可用:这通常是因为npm的bin目录不在PATH中。检查:
bash复制npm bin -g
确保该路径在你的PATH中。
4. 配置与问题排查
4.1 环境变量设置的玄机
Router需要几个关键环境变量才能正常工作:
bash复制export ANTHROPIC_BASE_URL="http://localhost:3456"
export ANTHROPIC_API_KEY="dummy"
这里有几个容易出错的地方:
-
ANTHROPIC_BASE_URL必须精确匹配,包括http://前缀和端口号。我曾因为漏写http://导致连接失败。
-
ANTHROPIC_API_KEY可以是任意字符串,但绝不能为空。建议使用"sk-ant-dummy123"这样的格式,因为:
- 它符合API key的一般格式
- 当你在日志中看到这个值时,能立即识别它是占位符
-
这些变量应该放在~/.bashrc或~/.zshrc中,但要注意不要被其他脚本覆盖。我习惯在文件末尾添加:
bash复制# Claude Router配置
export ANTHROPIC_BASE_URL="http://localhost:3456"
export ANTHROPIC_API_KEY="sk-ant-dummy123"
unset ANTHROPIC_AUTH_TOKEN # 确保没有冲突的token
4.2 Router配置文件详解
配置文件~/.claude-code-router/config.json的结构很有讲究:
json复制{
"Providers": [
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/v1/chat/completions",
"api_key": "sk-xxxxxxxxxxxxx",
"models": ["deepseek-chat", "deepseek-reasoner"],
"transformer": {
"use": ["deepseek", "tooluse"]
}
}
],
"Router": {
"default": "deepseek,deepseek-chat",
"think": "deepseek,deepseek-chat"
}
}
关键注意事项:
-
api_base_url末尾不能有斜杠,否则会导致路由错误。
-
models列表中的名称必须与API文档完全一致,大小写敏感。
-
transformer配置决定了请求的转换方式。"tooluse"表示支持工具调用,这对代码补全特别重要。
-
Router部分定义了两个路由:
- default:普通请求使用的模型
- think:复杂推理任务使用的模型
经验分享:deepseek-reasoner虽然在某些任务上表现更好,但不支持工具调用。这就是为什么我们要把think路由也设为deepseek-chat。
4.3 启动顺序的最佳实践
正确的启动顺序很重要:
- 首先启动Router服务:
bash复制ccr start
- 验证服务状态:
bash复制ccr status
应该看到"Router is running"。
- 启动Claude Code:
bash复制ccr code
这个命令做了三件事:
- 检查并启动Router(如果未运行)
- 设置必要的环境变量
- 启动Claude Code交互界面
我强烈建议使用ccr code而不是直接运行claude,因为它处理了很多边缘情况。
5. 高级调试技巧
5.1 查看Router日志
当出现问题时,查看日志是第一步:
bash复制journalctl -u claude-code-router -n 50 --no-pager
如果没有journalctl,可以查看直接输出:
bash复制ccr start --foreground
这会在前台运行Router并输出日志到控制台。
5.2 验证API连通性
有时问题出在DeepSeek API连接上。可以用curl测试:
bash复制curl -X POST \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-chat","messages":[{"role":"user","content":"Hello"}]}' \
https://api.deepseek.com/v1/chat/completions
如果这个命令失败,说明问题不在Router,而在API连接本身。
5.3 使用替代端口
3456端口可能被占用。可以修改配置使用其他端口:
- 编辑Router配置,添加:
json复制"server": {
"port": 3457
}
- 同时更新ANTHROPIC_BASE_URL:
bash复制export ANTHROPIC_BASE_URL="http://localhost:3457"
- 重启Router:
bash复制ccr restart
6. 性能优化建议
6.1 调整请求超时
默认超时可能不适合所有场景。可以在配置中添加:
json复制"server": {
"timeout": 30000
}
单位为毫秒,这个例子设为30秒。
6.2 启用请求缓存
对于重复性问题,可以启用缓存:
json复制"cache": {
"enable": true,
"ttl": 3600
}
ttl是缓存存活时间(秒)。
6.3 并发控制
防止过多请求压垮API:
json复制"concurrency": {
"max": 5
}
限制同时进行的API请求数量。
7. 日常使用技巧
7.1 快速切换模型
不需要编辑配置文件,可以使用交互命令:
bash复制ccr model
这会列出可用模型,选择后自动更新配置并重启Router。
7.2 查看当前配置
bash复制ccr config
显示当前生效的配置,比直接看文件更直观。
7.3 临时使用官方API
如果想临时切换回Anthropic官方API:
bash复制unset ANTHROPIC_BASE_URL
claude
记得设置有效的ANTHROPIC_API_KEY。
8. 安全注意事项
- API密钥保护:
- 不要将config.json提交到Git
- 设置文件权限:
bash复制chmod 600 ~/.claude-code-router/config.json
- 本地服务安全:
- Router默认只监听127.0.0.1,不要改为0.0.0.0
- 考虑添加简单的认证:
json复制"server": {
"auth": "username:password"
}
- 定期更新:
- 检查Router更新:
bash复制npm outdated -g @musistudio/claude-code-router
9. 疑难问题解决方案
9.1 突然停止响应
现象:Router运行一段时间后不再响应请求。
可能原因:
- 内存泄漏
- API连接问题
解决方案:
- 设置自动重启:
bash复制ccr start --watch
- 或者使用进程管理器如pm2:
bash复制npm install -g pm2
pm2 start ccr -- start
pm2 save
pm2 startup
9.2 返回结果截断
现象:长回答被截断。
解决方法:
- 在config.json中调整:
json复制"transformer": {
"max_tokens": 4096
}
- 或者在Claude Code中使用分段请求。
9.3 编码问题
现象:非ASCII字符显示异常。
解决方法:
- 确保终端使用UTF-8:
bash复制echo $LANG
应该是en_US.UTF-8或类似。
- 在Router配置中添加:
json复制"transformer": {
"encoding": "utf-8"
}
10. 与IDE集成
10.1 VS Code配置
- 安装Claude Code扩展
- 修改设置:
json复制"claude.serverUrl": "http://localhost:3456",
"claude.apiKey": "sk-ant-dummy123"
- 重启VS Code
10.2 JetBrains系列
- 安装Claude插件
- 配置Host为localhost:3456
- API Key填任意非空值
10.3 远程开发
如果Router运行在远程服务器上:
- 设置SSH隧道:
bash复制ssh -L 3456:localhost:3456 user@remote
- 在本地使用:
bash复制export ANTHROPIC_BASE_URL="http://localhost:3456"
