Claude Code 接入 Gemini Pro 完整教程 - 用 Google 模型驱动 Claude Code

很多人装好 Claude Code 之后，第一个想试的”非 Claude 模型”就是 Google 的 Gemini。原因很直接：Gemini 1.5 Pro 的 1M 上下文 是目前几款主流商用大模型里最长的，原生多模态对图片、PDF、音频的处理能力也很强，加上 Google AI Studio 给出的价格在长上下文档位里相当有竞争力。于是 ClaudeCode 接入 GeminiPro、ClaudeCode 接入 Gemini、Claude Code 接入其他模型 就成了搜索热门。

本文用一篇的篇幅把 ClaudeCode 能接入其他模型吗 的答案讲清楚——能，但要走桥接层；并给出 Gemini 这条路完整的配置示例、真实使用体验、已知兼容性坑、以及什么场景该用什么场景不该用。所有命令、配置截至本文撰写时有效，具体接口字段以 Google 官方文档为准。

为什么会想用 Claude Code 跑 Gemini

Claude Code 是个非常好用的 CLI 编程助手，但模型不一定非要是 Claude。把 Gemini 接进来通常是冲着这几点：

诉求	Gemini 的优势
超长上下文	Gemini 1.5 Pro 默认 1M token，2.0 Pro 在此基础上延续
多模态	原生支持图片、PDF、视频、音频输入
价格	长上下文档位价格相对友好，超出阈值有梯度计费
免费层	Google AI Studio 给个人开发者一定的免费额度
区域可达	部分海外区域对 Gemini API 的直连更顺

但要注意：Claude Code 的客户端协议是 Anthropic Messages API，Gemini 用的是 Google 自己的 generativelanguage API 或 Vertex AI 协议，两者请求体、流式格式、工具调用 schema 都不一样。所以”接入”不是改个 URL 就行，要在中间放一层协议转换网关。

如果想看 Claude Code 切到其他模型的通用方法（Opus / Sonnet / Haiku 内部切换、接 GLM / DeepSeek / Ollama），可以参考 /blog/claude-code-switch-model.html，本文聚焦 Gemini 这条路。

前置：拿到 Gemini API Key

Gemini 的 API key 有两种来源，价格、配额、合规要求都不一样，先选清楚。

来源 A：Google AI Studio（个人开发者首选）

• 入口：aistudio.google.com
• 用 Google 账号登录，左侧 “Get API key”
• 创建一个项目，生成 key（形如 AIza...）
• 默认带一定免费层（具体配额以官方为准）

适合个人开发、原型验证、教程学习。免费额度对小项目够用，超出后按量付费。

来源 B：Vertex AI（企业 / 生产首选）

• 入口：Google Cloud Console → Vertex AI
• 需要先开通计费、创建 GCP 项目、启用 Vertex AI API
• 调用走 aiplatform.googleapis.com 或区域端点
• 认证用 GCP service account JSON

适合企业、生产环境、需要 SLA 和数据合规承诺的场景。

两条路的核心区别：

维度	AI Studio	Vertex AI
注册门槛	Google 账号即可	需要 GCP 计费账号
认证方式	API key	OAuth / service account
数据合规	默认条款	企业级合规、可选区域
价格	公开标价	同公开价但走 GCP 账单
SLA	无强保障	企业级 SLA

国内开发者如果只是个人玩，优先 AI Studio 的 API key 模式，配置最简单。下文方案 A 默认走这条路。

协议差异：为什么必须桥接

Claude Code 启动后，所有请求会发到 ANTHROPIC_BASE_URL 配置的地址，请求体格式大致是：

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "hello"}
  ],
  "tools": [...],
  "stream": true
}

Gemini 的请求体长这样（generativelanguage API）：

{
  "contents": [
    {"role": "user", "parts": [{"text": "hello"}]}
  ],
  "tools": [{"functionDeclarations": [...]}],
  "generationConfig": {"maxOutputTokens": 1024}
}

两边在以下字段都不兼容：

• 消息结构：messages vs contents
• 内容块：Anthropic 的 content 数组（text / image / tool_use / tool_result）vs Gemini 的 parts
• 工具：tools[].input_schema vs functionDeclarations[].parameters
• 流式：Anthropic 用 SSE 自定义 event 类型，Gemini 用 SSE 但 chunk schema 不同
• 模型 ID：claude-sonnet-4-6 vs gemini-1.5-pro-latest

所以中间必须有一层做协议翻译。最成熟的开源方案是 LiteLLM。

方案 A：LiteLLM 桥接（推荐）

LiteLLM 是一个统一 100+ LLM 提供商的网关，可以同时暴露 OpenAI 和 Anthropic 兼容端点。把它跑在本地或一台小服务器上，让 Claude Code 通过它访问 Gemini。

1. 安装

需要 Python 3.10+：

pip install "litellm[proxy]"

或者用 Docker：

docker pull ghcr.io/berriai/litellm:main-latest

2. 创建配置

新建 litellm_config.yaml：

model_list:
  - model_name: claude-3-5-sonnet-20241022
    litellm_params:
      model: gemini/gemini-1.5-pro-latest
      api_key: os.environ/GEMINI_API_KEY

  - model_name: claude-opus-4-6
    litellm_params:
      model: gemini/gemini-2.0-pro-exp
      api_key: os.environ/GEMINI_API_KEY

  - model_name: claude-haiku-4-5
    litellm_params:
      model: gemini/gemini-1.5-flash-latest
      api_key: os.environ/GEMINI_API_KEY

litellm_settings:
  drop_params: true
  set_verbose: false

general_settings:
  master_key: sk-litellm-master-key-change-me

几个要点：

• model_name 写成 Anthropic 风格的 ID，是为了让 Claude Code 端配置不用动。
• litellm_params.model 才是 LiteLLM 后端真正调用的 Gemini 模型，前缀必须是 gemini/。
• drop_params: true 让 LiteLLM 自动丢掉 Gemini 不认识的字段（比如 Anthropic 特有的 top_k、stop_sequences 某些写法）。
• master_key 是 LiteLLM 自己的 API key，跟 Gemini key 不是一回事，Claude Code 端会用这个。

3. 启动网关

export GEMINI_API_KEY="AIza..."
litellm --config litellm_config.yaml --port 4000

Windows PowerShell：

$env:GEMINI_API_KEY = "AIza..."
litellm --config litellm_config.yaml --port 4000

成功后会看到类似 Uvicorn running on http://0.0.0.0:4000 的日志。

4. 配置 Claude Code

编辑 ~/.claude/settings.json（Windows 是 %USERPROFILE%\.claude\settings.json）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_API_KEY": "sk-litellm-master-key-change-me"
  },
  "model": "claude-3-5-sonnet-20241022"
}

或者临时通过环境变量：

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-litellm-master-key-change-me"
claude

5. 验证

最快的方法是问一句”你是谁、谁训练的、模型版本号”，正常情况下会回到 Gemini 的自报家门。或者用 curl 直接打 LiteLLM：

curl -X POST http://localhost:4000/v1/messages \
  -H "x-api-key: sk-litellm-master-key-change-me" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":200,"messages":[{"role":"user","content":"What model are you?"}]}'

返回的 JSON 顶层字段会是 Anthropic 风格的 id / type / role / content，但内容来自 Gemini。

方案 B：Vertex AI 路径要避免的混淆

很多人看到 “Anthropic 的 Claude 也在 Vertex AI 上提供” 这条消息，会误以为 Vertex AI 那条线能同时跑 Claude 和 Gemini，所以 Claude Code 配上 Vertex 就能用 Gemini 了。这是个典型误解。

渠道	跑的模型	Claude Code 怎么用
Vertex AI 上的 Claude	还是 Claude（Anthropic 原版）	直接配 Vertex 凭证
Vertex AI 上的 Gemini	Gemini（Google 自家）	仍然要 LiteLLM 桥接

也就是说 Vertex 只是 Google Cloud 提供的统一模型托管平台，它把不同厂商的模型放在一起卖，但每个模型还是自己的协议。Vertex 上的 Claude 用 Anthropic 协议，Vertex 上的 Gemini 用 Google 协议。Claude Code 客户端只懂 Anthropic 协议，所以接 Vertex 上的 Gemini 仍然绕不开桥接层。

如果你已经在 GCP 上，LiteLLM 也支持直接配 Vertex 的 Gemini：

model_list:
  - model_name: claude-3-5-sonnet-20241022
    litellm_params:
      model: vertex_ai/gemini-1.5-pro-001
      vertex_project: your-gcp-project
      vertex_location: us-central1

LiteLLM 会用本地 gcloud auth application-default login 的凭证或者 GOOGLE_APPLICATION_CREDENTIALS 指向的 service account JSON 完成认证。

实测：Gemini 1.5 Pro 在 Claude Code 里的体验

桥接通了之后，跑几类典型任务的主观感受（仅供参考）：

单文件编辑

读一个 800 行的 Python 文件，让它加一个错误处理 + 完整 docstring。Gemini 1.5 Pro 输出质量良好，速度和 Sonnet 接近。但 tool_use 调用 Edit 工具时，偶尔会把多段修改合并成一个超大 patch，需要在 prompt 里强调”一次只改一段”。

跨文件检索

打开一个 200 文件的 monorepo 问”这个函数的所有调用方”。Gemini 1.5 Pro 的 1M 上下文优势在这里体现出来——可以一次性塞进半个仓库做语义搜索，避免 Claude Code 默认的 grep + 重复读文件的来回。但 Gemini 默认不会主动 grep，得在 prompt 里明示。

多文件重构

把一个 React class 组件批量改写成 hooks。Gemini 能完成，但每改完一个文件经常要再追问 “下一个”，连续 agentic 编辑的自驱力不如 Claude Opus。

长 PR 描述

读完一个 30 文件的 diff 写 PR 描述。Gemini 1.5 Pro 的长上下文让它能一次看完，输出也成体系。这类长输入短输出任务是它的甜点区。

Gemini 的优势

• 1M 上下文是真的能用：Claude Code 在超大代码库场景下，传统 Sonnet/Opus 经常要靠 sub-agent 分批读，Gemini 可以一次塞进去。
• 多模态原生：丢图片、PDF、设计稿进去直接分析，不需要先转 base64 再考虑模型支持。
• 价格：长上下文档位单价比 Opus 低不少，做”读海量文档 + 短回答”的任务非常划算。
• 免费层：AI Studio 个人开发者有免费 quota，做小工具不花钱。

Gemini 的劣势

• 工具调用兼容性：Anthropic Messages API 的 tool_use / tool_result 流转换成 Gemini 的 functionCall / functionResponse 有损耗，复杂工具链（Claude Code 里有 Read / Edit / Bash / WebFetch / TodoWrite 等十几个工具）偶尔会触发字段丢失或 schema 校验失败。LiteLLM 版本更新很快，遇到问题先升级再排查。
• 流式 chunk 节奏：Gemini 的 SSE chunk 粒度跟 Anthropic 不一致，Claude Code 的进度显示偶尔会卡顿（不影响最终输出）。
• Agent 自驱力：Claude 4 系列在多步 agentic 任务里很强，Gemini 1.5 Pro 比较”被动”，需要 prompt 引导。
• reasoning tokens：Anthropic 的 thinking / Gemini 的 thought 概念不完全对齐，开启思考模式时计费和输出方式都有差异。
• 国内网络：generativelanguage.googleapis.com 国内不能直连，得用海外服务器跑 LiteLLM 或合规渠道。

已知兼容性问题清单

问题	表现	缓解
tool_use 输入 schema 转换失败	模型不调用工具或参数错乱	升级 LiteLLM、简化 schema、开 drop_params
多轮 tool_result 历史过长	Gemini 报 “Invalid content”	控制单会话工具调用次数，或开启 Claude Code 的 /compact
流式中途断开	Claude Code 提示连接中断	重试、检查 LiteLLM 日志、关闭 stream 试一次
系统提示词过长	Gemini 拒绝或截断	LiteLLM 会把 system 折叠到首条消息，超长拆段
中文 token 计数差异	价格/限速估算不准	以 Gemini 实际返回的 usage 字段为准

适合 / 不适合的场景

适合用 Gemini 接 Claude Code：

• 单次需要喂超大代码库 / 几百页 PDF 做摘要分析
• 多模态任务（看截图改 UI、读架构图）
• 个人项目、原型，想薅免费 quota
• 长输入 + 短输出（成本最划算）

不太适合：

• 多步 agentic 编程（连续改十几个文件）—— Opus 4.6 更稳，参考 /blog/claude-opus-46-deep-dive.html
• 对工具调用稳定性要求极高的生产场景
• 短输入 + 短输出的高频小任务（Haiku / 国产模型性价比更好）
• 没有海外网络的国内开发环境（部署成本高）

切回 Claude 原生

随时可以切回，桥接层不破坏任何 Claude Code 配置：

# 临时切回（关掉环境变量）
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_API_KEY  # 如果之前设过 LiteLLM 的 key

# 重新设回 Anthropic 官方
export ANTHROPIC_API_KEY="sk-ant-..."
claude

或者在 settings.json 里准备两套 profile，需要时改一行：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

想把 Gemini 和 Claude 同时挂着、按任务路由，可以让 LiteLLM 配置里同时列两家模型，Claude Code 启动时用 --model 指定具体走哪个 model_name。

常见问题

LiteLLM 必须自己跑吗？

不一定。生产环境可以部署在云上 / k8s 上，把 LiteLLM 当成团队共享网关。本地开发 4000 端口最方便，公开端口务必加 master_key 限流，不要裸奔。

能用 Gemini 2.0 / 2.5 系列吗？

可以，LiteLLM 持续跟进 Gemini 新模型，把 litellm_params.model 改成对应的 gemini/gemini-2.0-pro-exp、gemini/gemini-2.5-pro 等。模型 ID 以 Google 官方发布为准。

Gemini 的 1M 上下文真的能填满吗？

理论支持，但实际有几个限制：单请求最大 token 数、模型在 80% 上下文之后效果下降的”长上下文衰减”、价格快速上升。塞 90% 通常没必要，按需用。

接入后还能用 Claude Code 的 sub-agent / hooks 吗？

能。Sub-agent 和 hooks 是 Claude Code 客户端层的能力，跟后端是哪个模型无关。不过 sub-agent 编排在 Gemini 上的表现不如在 Claude 上稳。

跟 Claude API 中转有什么区别？

中转一般是把”声称的 Claude 模型 ID”指向某个第三方实际跑的模型（可能是 Claude、也可能不是）。LiteLLM 是开源的、协议透明、跑在自己机器上，明确知道每个请求去哪。两条路都能工作，LiteLLM 在可控性和可观测性上更胜一筹。

价格估算

Gemini 1.5 Pro 长上下文场景下，输入价格通常显著低于 Claude Opus，输出价格也有竞争力。具体到每百万 token 的数字，请去 ai.google.dev/pricing 查最新表，与 /blog/claude-api-pricing-guide.html 给的 Claude 价格做对比。以官方为准。

---

把 Gemini 接进 Claude Code 本质上是用 Claude Code 的工程化能力 + Gemini 的长上下文。配置不复杂，LiteLLM 一层网关就够，难点在理解协议差异 + 处理工具调用的兼容性。如果你的工作流里有大量”读海量内容、产出结构化结果”的任务，这条路值得尝试；如果是高频 agentic 编程，原生 Claude 仍然是更稳的选择。