Claude Code配置本地Ollama模型或别的模型(Deepseek等)的实践指南

个人使用场景 claude 模型实在是太贵了，想使用 Claude Code 默认只支持 Anthropic 的接口格式，所以本文记录了如何把本地模型或者其他模型（Deepseek等）接入 Claude Code 使用的方法。

通过 Claude Code Router (CCR) 将 Claude Code CLI 连接到 Ollama（本地模型）或 DeepSeek（云端模型），从而使用非 Anthropic 模型运行 Claude Code。

1. 原理概述

架构图

┌─────────────────┐      Anthropic Messages API       ┌──────────────────────────┐
│                 │  ──────────────────────────────▶   │                          │
│   Claude Code   │      /v1/messages                 │  Claude Code Router      │
│   (CLI / VSC)   │  ◀──────────────────────────────   │  (localhost:3456)        │
│                 │                                    │                          │
└─────────────────┘                                    └──────────┬───────────────┘
                                                                  │
                           ┌──────────────────────────────────────┼──────────────────────────┐
                           │                                      │                          │
                           ▼                                      ▼                          ▼
                  ┌──────────────────┐                  ┌──────────────────┐      ┌──────────────────┐
                  │   Ollama         │                  │   DeepSeek API   │      │   OpenAI API     │
                  │   (localhost)    │                  │   (云端)          │      │   (其他兼容)      │
                  │   :11434/v1      │                  │   api.deepseek   │      │                  │
                  └──────────────────┘                  └──────────────────┘      └──────────────────┘

工作流程

1. Claude Code 原生只支持 Anthropic Messages API 格式（/v1/messages）
2. Claude Code Router 运行在本地，暴露一个兼容 Anthropic API 的端点 http://127.0.0.1:3456
3. 通过设置 ANTHROPIC_BASE_URL=http://127.0.0.1:3456，Claude Code 将所有 API 请求发送到 CCR
4. CCR 内部做协议转换：将 Anthropic Messages 格式翻译成 OpenAI Chat Completions 格式（Ollama / DeepSeek 都支持）
5. 响应再从 OpenAI 格式翻译回 Anthropic 格式返回给 Claude Code

关键事实

2. 安装 Claude Code Router

系统要求

• macOS 10.15+ / Windows 10+ / Linux (支持 AppImage)
• 已安装 Claude Code CLI

下载安装

1. 访问 GitHub Releases 页面
2. 下载对应系统的安装包：
   • macOS: .dmg 文件
   • Windows: .exe 安装程序
   • Linux: .AppImage 文件
3. 安装并启动应用

首次启动

启动后，CCR 会在以下位置创建配置文件：

• macOS / Linux: ~/.claude-code-router/config.json
• Windows: %APPDATA%\Claude Code Router\config.json

3. 配置 Ollama 提供商

前置条件

• 已安装 Ollama
• 已拉取至少一个模型，例如：

ollama pull llama3.1
ollama pull qwen2.5
ollama pull deepseek-r1:7b

• Ollama 服务正在运行（默认监听 http://127.0.0.1:11434）

通过 CCR 界面配置

1. 打开 CCR 桌面应用
2. 进入 Providers → 点击 Add Provider
3. 填写以下信息：

4. 点击 Save

为什么 Ollama 的 endpoint 是 :11434/v1？ Ollama 从 0.1.32 版本开始原生支持 OpenAI 兼容 API，路径为 /v1/chat/completions。 CCR 通过 openai_chat_completions 协议将 Anthropic 请求转换后发送到此端点。

通过 Deeplink 配置（可选）

也可以直接通过 URL Scheme 快速添加：

ccr://provider?name=Ollama&base_url=http%3A%2F%2F127.0.0.1%3A11434%2Fv1&api_key=ollama&models=llama3.1,qwen2.5&protocol=openai_chat_completions

在浏览器中打开此链接，CCR 会弹出确认对话框。

测试 Ollama 连接

在终端验证 Ollama 的 OpenAI 兼容 API 是否正常：

curl http://127.0.0.1:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.1",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

应返回包含 choices 字段的 JSON 响应。

4. 配置 DeepSeek 提供商

前置条件

• 注册 DeepSeek 平台
• 获取 API Key（在控制台创建）

通过 CCR 界面配置

1. 打开 CCR 桌面应用
2. 进入 Providers → 点击 Add Provider
3. 填写以下信息：

4. 点击 Save

通过 Deeplink 配置（可选）

ccr://provider?name=DeepSeek&base_url=https%3A%2F%2Fapi.deepseek.com%2Fv1&api_key=sk-xxxxxxxxx&models=deepseek-chat,deepseek-reasoner&protocol=openai_chat_completions

DeepSeek 模型说明

5. 配置 Claude Code 连接到 CCR

5.1 启动 CCR 网关

1. 在 CCR 桌面应用中进入 Server
2. 点击 Start 启动网关服务
3. 确认状态：两个端点应处于运行状态：
   • Wrapper gateway: http://127.0.0.1:3456
   • Core gateway runtime: http://127.0.0.1:3457

建议勾选 Auto-start，这样每次开机 CCR 会自动启动网关。

5.2 创建 Claude Code 配置文件

方法 A：全局配置（推荐）

编辑 ~/.claude/settings.json（macOS/Linux）或 %USERPROFILE%\.claude\settings.json（Windows）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
    "ANTHROPIC_API_KEY": "ccr-local"
  }
}

ANTHROPIC_API_KEY 的值可以是任意非空字符串——CCR 作为本地网关不验证这个 key，但 Claude Code 要求必须有值才会绕过登录流程。

方法 B：项目级配置

在项目根目录创建 .claude/settings.local.json（此文件会自动被 gitignore）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
    "ANTHROPIC_API_KEY": "ccr-local"
  }
}

方法 C：Shell 环境变量（临时，适合测试）

export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
export ANTHROPIC_API_KEY=ccr-local

5.3 使用 CCR Profiles 自动配置（推荐）

CCR 提供了 Profile 功能，可以一键应用配置：

1. 在 CCR 中进入 Profiles
2. 选择 Claude Code
3. 选择目标模型（例如你在 Ollama 中配置的 llama3.1）
4. 点击 Apply — 这会自动设置环境变量并打开 Claude Code

5.4 配置 CCR 路由

在 CCR 的 Routing 面板中设置：

你还可以配置针对不同工作负载的路由规则：

• Background（后台任务）→ 可以用更便宜的模型
• Thinking（推理任务）→ 可以用更强的模型
• Subagent（子智能体）→ 可以用性价比更高的模型

6. 验证连接

6.1 快速测试（curl）

在配置好环境变量后，先用 curl 测试 CCR 网关是否正常响应：

curl -X POST http://127.0.0.1:3456/v1/messages \
  -H "Authorization: Bearer ccr-local" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "llama3.1", "max_tokens": 50, "messages": [{"role": "user", "content": "Say hello"}]}'

注意：这里的 model 名称必须与你之前在 CCR 中添加的模型名称一致。 如果 DeepSeek 使用 deepseek-chat，如果 Ollama 使用你拉取的模型名如 llama3.1。

如果返回 JSON 且包含 content 字段，说明 CCR 工作正常。

6.2 启动 Claude Code

cd your-project
claude

如果一切正常，Claude Code 应该 跳过登录界面，直接进入会话。

6.3 检查状态

在 Claude Code 中运行：

/status

查看以下关键信息：

6.4 发送测试消息

尝试发送一条简单的消息，比如：

Hello, what model are you running on?

如果 CCR 路由配置正确，你会收到模型回复，并能在 CCR 的 Dashboard 中看到请求记录。

7. 进阶：路由规则与虚拟模型

7.1 多模型路由

CCR 支持根据请求特征将不同任务路由到不同模型：

配置方式：在 CCR → Routing → Add Routing Rule 中设置。

7.2 虚拟模型（Virtual Models）

可以创建虚拟模型名称来简化模型选择：

llama3.1 → Ollama 上的 llama3.1
default-coding → deepseek-chat
default-reasoning → deepseek-reasoner

在 CCR → Routing → Virtual Models 中配置。

7.3 备用路由（Fallback）

当主模型不可用时，CCR 可以自动切换到备用模型：

Primary:   deepseek-chat (DeepSeek)
Fallback:  llama3.1 (Ollama，本地运行，不需要网络)

在 Routing → 编辑路由规则 → 配置 Fallback 模型。

7.4 API Key 轮转

对 DeepSeek 等 API 服务，可以配置多个 API Key 实现负载均衡和故障转移：

在 Providers → 编辑 DeepSeek → API Key 字段使用逗号分隔多个 key：

sk-key1,sk-key2,sk-key3

CCR 会在请求失败时自动轮换到下一个 key。

8. 常见问题排查

8.1 Claude Code 仍然显示登录界面

原因：CCR 的网关配置未被 Claude Code 读取到。

解决：

• 确认 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY 都已正确设置
• 如果使用 settings.json，确认文件路径正确：
  • 全局：~/.claude/settings.json
  • 项目级：.claude/settings.local.json
• 运行 echo $ANTHROPIC_BASE_URL 检查环境变量是否生效
• 在 Claude Code 中运行 /status 查看实际生效的 base URL

8.2 连接被拒绝（Connection Refused）

原因：CCR 网关未启动。

解决：

• 确认 CCR 桌面应用正在运行
• 在 CCR → Server 中确认 Gateway 状态为 "Running"
• 检查端口是否被占用：lsof -i :3456

8.3 模型返回错误或不响应

原因：可能存在多种问题。

解决步骤：

对于 Ollama：

# 检查 Ollama 服务状态
ollama list
# 确认模型已加载
ollama run llama3.1
# 检查 Ollama 日志
ollama serve

对于 DeepSeek：

# 直接测试 DeepSeek API
curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "hi"}]}'

8.4 401 认证错误

原因：API Key 未正确传递。

解决：

• 如果使用 ANTHROPIC_API_KEY，CCR 收到的是 x-api-key 头
• 如果使用 ANTHROPIC_AUTH_TOKEN，CCR 收到的是 Authorization: Bearer 头
• 大多数情况下，两者都可以，只需确保 settings.json 中的变量名与 CCR 期望的一致

8.5 协议转换错误

原因：CCR 在 Anthropic Messages ↔ OpenAI Chat Completions 之间转换时可能遇到不兼容的字段。

解决：

• 在 Claude Code 中设置环境变量：CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
• 这会让 Claude Code 少发送一些实验性字段，降低协议转换出错的概率
• 在 settings.json 中添加：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
    "ANTHROPIC_API_KEY": "ccr-local",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

8.6 检查 CCR 日志

CCR 桌面应用中的 Network Logs 面板可以查看所有通过的请求和响应，是排查问题的最佳工具。

8.7 重置配置

如果需要完全重置：

# 备份现有配置
cp ~/.claude-code-router/config.json ~/.claude-code-router/config.json.bak
# 删除配置（CCR 会在下次启动时重新创建）
rm ~/.claude-code-router/config.json
# 清除 Claude Code 缓存
rm -rf ~/.claude/cache

9. 完整配置示例

最终~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
    "ANTHROPIC_API_KEY": "ccr-local",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

启动顺序

正确的启动顺序是：

1. 启动 Ollama（如果用本地模型）：ollama serve
2. 启动 CCR 并确保网关处于 Running 状态
3. 启动 Claude Code：claude

以上就是Claude Code配置本地Ollama模型或别的模型(Deepseek等)的实践指南的详细内容，更多关于Claude Code配置本地Ollama模型的资料请关注脚本之家其它相关文章！

最新评论