Gemma 4 接入 Claude Code Router：本地化 AI 编程环境搭建指南（2026）
Claude Code 是 Anthropic 推出的终端 AI 编程工具，以上下文理解和代码生成质量著称。但它默认且唯一支持的后端是 Anthropic 的云端 API —— 这意味着你的代码必须上传到它的服务器，每次使用都会产生 API 费用。
对于在意代码隐私、需要离线工作、或处在受限网络环境下的开发者来说，这是一个实际的痛点。Claude Code Router（CCR） 是社区开发的开源代理工具，它拦截 Claude Code 发出的 API 请求，再转发到你指定的后端 —— 比如本地 Ollama 上运行的 Gemma 4。
这篇指南会带你走通完整流程：安装 CCR、配置 Gemma 4 后端、实际使用，以及你必须了解的合规、质量和支持层面的限制。我们不鼓吹这套方案，它属于灰色地带，希望你在了解完整代价后再做决定。
为什么有人想让 Claude Code 跑本地模型？
在动手前先理解需求的合理性，下面是三个真实场景：
企业合规代码库。 金融、国防、医疗、政务这些行业的代码不允许离开内网，Anthropic 的 ToS 不会改变这一点。本地模型跑在自己的机器上，代码不出网络边界。
弱网或完全离线。 远程办公遇到烂 Wi-Fi、长途飞行、野外科研、保密实验室 —— 云端 API 随时失效，本地模型不受影响。
自定义或微调模型。 你可能在研究特定领域微调的 Gemma 4（生物信息、EDA、内部 DSL），希望套用 Claude Code 的交互，但换上自己的权重。
这些都是合理的工程需求，和"不想付费"是不同的动机，这篇文章不帮后者辩护。
合规与法律声明（动手前请先读）
免责声明： 下面的操作会修改 Claude Code 的上游 API 端点，指向一个第三方本地代理。根据 Anthropic 服务条款的演进，这可能违反 Claude Code 的使用协议，并让你的 Anthropic 账号面临被终止的风险。本文是技术文档，不构成法律意见。如果你在公司内部部署，请先让法务和安全团队过一遍。
除了法律风险，还有这些技术代价要接受：
- 功能降级。 Claude Code 的 extended thinking、prompt caching、部分 tool use 格式是针对 Anthropic 模型深度优化的。换成 Gemma 4 后这些能力可能降级、异常或静默失效。
- 输出质量差距。 Gemma 4 26B / 31B 是优秀的开源模型，但在复杂多文件推理上仍落后于 Claude 3.5 / 4。请把预期调低。
- 社区项目，无 SLA。 CCR 是社区志愿维护的开源项目，Anthropic 任何协议变更都可能让它一夜失效，没有商业支持可以兜底。
能接受以上代价，再往下看。
Claude Code Router 到底是什么？
CCR 是一个轻量级本地 HTTP 代理，通常用 Node.js 写成。它做的事情很窄：
- 在本地监听一个端口。
- 接收形如 Anthropic Messages API 的请求。
- 将请求转换为 OpenAI 兼容格式（Ollama / LiteLLM / OpenRouter 等）。
- 再把流式响应转换回 Claude Code 期望的格式。
关键在于格式转换：消息角色、tool call 块、流式 delta、stop reason 在两套 API 间差异很大，CCR 把这些磨平，让 Claude Code 以为自己还在和 Anthropic 说话。
准备工作
- Node.js 18+（CCR 是 Node 项目）
- Ollama 已安装并运行（ollama.com）
- Gemma 4 26B 或 31B 通过 Ollama 拉取完成
- Claude Code（
npm install -g @anthropic-ai/claude-code） - 硬件：26B 至少 16 GB 内存，31B 至少 24 GB。硬件选型见文末相关文章。
第一步：安装 Claude Code Router
克隆仓库并安装依赖：
git clone https://github.com/<org>/claude-code-router.git
cd claude-code-router
npm install仓库地址因 fork 而异。CCR 是社区项目，可能会被重命名或活跃在不同分支。请在 GitHub 搜索 "claude code router" 或 "claude code proxy"，挑最近有提交的维护分支。
第二步：把 CCR 指向 Ollama
在 CCR 目录下创建 .env（或 config.json，取决于你选的 fork）：
UPSTREAM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=gemma4:26b-a4b
PORT=8082启动代理：
npm start应该看到类似输出：
Claude Code Router started on port 8082
Upstream: ollama (gemma4:26b-a4b)
Ready to accept connections简单验证一下：
curl http://localhost:8082/v1/models应该返回包含 Gemma 4 模型的 JSON 列表。
第三步：让 Claude Code 连到 CCR
Claude Code 通过 ANTHROPIC_BASE_URL 决定 API 端点。把它指向本地代理：
export ANTHROPIC_BASE_URL="http://localhost:8082"
export ANTHROPIC_API_KEY="local" # 必须非空，值本身不重要
claudeClaude Code 正常启动，但所有请求都会走 CCR 转发到本地 Gemma 4。
不想每次改环境变量，可以写进 ~/.zshrc / ~/.bashrc，或者用 alias 隔离默认行为：
alias claude-local='ANTHROPIC_BASE_URL=http://localhost:8082 ANTHROPIC_API_KEY=local claude'这样 claude 仍然走官方 API，claude-local 才走本地 Gemma 4。
第四步：实战使用
代码解释：
> 解释一下 src/auth/middleware.ts 这个文件在做什么Gemma 4 会读文件并给出总结。单文件解释尚可，跨模块的深度推理是它的短板。
生成新端点：
> 在 src/api/ 下新建 health.ts，实现 GET /api/health，返回状态与版本号CRUD 与 HTTP 脚手架类任务表现不错。
修 Bug：
> npm test 报 "Cannot read properties of undefined"，帮我看 src/utils/parser.ts有明确堆栈信息时，Gemma 4 通常能定位问题；没有错误信号的隐性 Bug，效果明显打折。
真实体验对比表
| 维度 | 原版 Claude Code | CCR + Gemma 4 26B | CCR + Gemma 4 31B |
|---|---|---|---|
| 代码生成质量 | 极强 | 中等（GPT-3.5 级） | 良好（接近 GPT-4） |
| 多文件理解 | 极强 | 较弱 | 中等 |
| Tool use 兼容 | 完美 | 部分异常 | 部分异常 |
| Extended thinking | 支持 | 不支持 | 不支持 |
| 响应速度 | 快（云端） | 20–40 t/s | 15–30 t/s |
| 隐私 | 代码出网 | 完全本地 | 完全本地 |
| 离线可用 | 否 | 是 | 是 |
| 月费用 | API 按量 | 0 元 | 0 元 |
适合：简单代码生成、解释代码、修简单 Bug、离线/受限环境临时使用。
不适合：复杂架构重构、长上下文多文件修改、依赖 extended thinking 的深度推理。
和其他本地 AI 编程方案的对比
| 方案 | 原生本地支持 | 需要代理 | Git 集成 | 多文件编辑 | 成熟度 |
|---|---|---|---|---|---|
| Aider + Gemma 4 | 原生 | 不需要 | 自动 commit | 强 | 高（30K+ stars） |
| Codex CLI + Gemma 4 | 需配置 | 不需要 | 无 | 单文件为主 | 中 |
| CCR + Claude Code + Gemma 4 | 不支持 | 需 CCR | 无 | 强（继承 Claude Code） | 低（实验性） |
| Cursor + Ollama | 需插件 | 不需要 | 无 | 强 | 中 |
实话实说： 如果你的核心诉求是"本地模型 + 终端编程"，Aider 是更成熟的答案 —— 它原生为本地后端设计。CCR 只在你已经深度绑定 Claude Code 工作流，且有明确的隐私/离线约束时才值得考虑。
常见故障排查
"Port already in use" —— 改 .env 里的 PORT，或干掉占用 8082 的进程：
lsof -i :8082
kill -9 <PID>Claude Code 报 "Authentication failed" —— 确认 ANTHROPIC_API_KEY 非空，ANTHROPIC_BASE_URL 指向 CCR 端口。
输出乱码或截断 —— CCR 的格式转换不完美。尝试 git pull && npm install 升到最新版、换 31B（格式遵从度更好）、或简化 prompt。
响应太慢 —— 用 ollama ps 确认 Ollama 在 GPU 上跑，内存紧张就考虑 GGUF 量化。
常见问题 FAQ
Q：用 CCR 会被 Anthropic 封号吗？ A：有风险。修改 Claude Code 的 API 端点可能违反 Anthropic ToS。我们无法给法律意见，建议谨慎评估；如果用于商业场景，务必先咨询法务。
Q：Gemma 4 能完全替代 Claude 吗？ A：不能。Claude Code 的 extended thinking、深度上下文、特定 tool use 格式都是围绕 Anthropic 模型优化的。Gemma 4 只能给你一个功能子集，不是平替。
Q：CCR 支持 Windows 吗？ A：支持。Node.js 和 Ollama 都跨平台，安装步骤一致。
Q：能接 GPT-4 或其他云端模型吗？ A：CCR 支持多种上游，包括 OpenAI。但这等于放弃了"本地隐私"的核心价值，并且仍要付上游的 API 费用。
Q：为什么不直接用 Aider 或 Codex CLI？ A：大多数情况下这才是正确答案。Aider 的 repo map 和自动 git commit 对本地模型场景更友好。只有当 Claude Code 的交互体验对你不可替代时再选 CCR，详见 Aider + Gemma 4 指南。
Q：Gemma 4 E2B / E4B 能用吗？ A：技术上可以转发到任何 Ollama 模型，但 4B / 8B 在 agentic 编程负载下达不到可用质量。最低建议 26B。
Q：能在团队里生产使用吗？ A：不建议。ToS 风险加上 CCR 是单人维护的社区项目，我们不会把它放到团队共享路径上。做个人研究或小范围试点可以，团队生产请谨慎。
相关文章
Stop reading. Start building.
~/gemma4 $ Get hands-on with the models discussed in this guide. No deployment, no friction, 100% free playground.
Launch Playground />
