OpenCode 接入 Gemini 完整指南

OpenCode 接入 Gemini 完整指南

本教程教你把 Google 的 AI「Gemini」接到 OpenCode 这个工具里，接好之后就能直接和 AI 聊天、让它帮你写代码、解释文档。

OpenCode 接入 Gemini 有两种方式，选一种就行：

前置准备

不管选哪种方式，都需要这两样东西：

• 一个 Google 账号（就是你的 Gmail）
• 电脑能上网

步骤一：装好 OpenCode

OpenCode 是个免费工具，先把它装到电脑上。

1. 打开终端

• Windows 用户：按键盘上的 Win + R，在弹出的小窗口里输入 cmd，然后回车，会弹出黑色的命令窗口。
• Mac 用户：按 Command + 空格，输入「终端」三个字，回车打开。

2. 复制下面这一行命令，粘贴到终端里，按回车

1curl -fsSL https://opencode.ai/install | bash

3. 启动 OpenCode

装好之后，在终端里输入下面这个词并回车：

1opencode

你会看到一个蓝紫色的全屏界面，这就是 OpenCode 的「主页」，下面所有操作都在这里完成。

步骤二：领一个 Gemini 的「通行证」

OpenCode 只是个「壳」，它本身没有 AI，需要你给它配一个 AI 来源。我们用 Google 的 Gemini，但要先去 Google 领一张「通行证」（专业说法叫 API Key，你可以理解成一张门禁卡）。

1. 打开 Google AI Studio

在浏览器里访问：https://aistudio.google.com/apikey

用你的 Gmail 账号登录。第一次进去会让你同意服务条款，点同意即可。

2. 创建通行证

1. 点击页面上的 「Get API key」 按钮
2. 再点击 「Create API key」
3. 下面会弹出一个项目选择框，直接选默认的（或点「Create API key in new project」）就行
4. 稍等几秒，页面会显示一串以 AIzaSy... 开头的长字符串，这就是你的通行证

3. 复制通行证

点通行证旁边的「复制」按钮（或手动选中复制），把它存到记事本里备用。

步骤三：接入 Gemini

从这里开始，方式 A 和方式 B 分开走，选一种跟着做即可。

方式 A：应用端交互接入（推荐新手）

回到刚才 OpenCode 的全屏界面，我们要告诉它「我要用 Gemini」。

A1. 输入 /connect 命令

在 OpenCode 最下方的输入框里（看起来像个长条输入区域），输入这一行：

然后按回车。

A2. 在弹出的列表里选 Google

回车后，屏幕中间会弹出一个列表，里面是一排 AI 来源的名字（Anthropic、OpenAI、Google 等）。操作方式：

• 用键盘的 ↑ ↓ 方向键上下移动，让高亮条停在 Google 上
• 按 回车 确认选择

A3. 粘贴通行证

屏幕会变成一个输入框，提示你输入 API key：

• 按 Ctrl + V（Mac 是 Command + V）把刚才存的通行证粘进去
• 按 回车 确认

A4. 看到成功提示

屏幕出现 Successfully authenticated（认证成功）字样，就说明 Gemini 已经成功加进来了！

方式 B：配置文件手动接入（进阶）

如果你更喜欢直接改配置文件，可以跳过 /connect，手动编辑 OpenCode 的配置。

B1. 找到（或新建）配置文件

OpenCode 的配置文件叫 opencode.json，一般放在项目根目录或用户目录下。如果没有就新建一个。

B2. 写入 Gemini 提供商配置

打开 opencode.json，加入下面这段（把 你的-api-key 换成步骤二领到的通行证）：

1{
2  "providers": {
3    "gemini": {
4      "apiKey": "你的-api-key",
5      "baseURL": "https://generativelanguage.googleapis.com/v1",
6      "models": ["gemini-2.5-flash", "gemini-2.5-pro"],
7      "defaultModel": "gemini-2.5-flash"
8    }
9  },
10  "defaultProvider": "gemini"
11}

关键字段含义：

• apiKey：步骤二领到的通行证
• baseURL：Gemini 的 API 地址（注意要带 /v1，少了会报 404）
• models：你要用的模型列表
• defaultModel：默认用哪个模型
• defaultProvider：默认用哪个来源（这里设成 gemini）

B3. 启动 OpenCode 验证配置生效

保存配置文件后，在终端启动 OpenCode：

1opencode

如果配置写对了，启动后顶部会显示当前来源是 google/gemini-...，说明配置已生效。

步骤四：挑一个 Gemini 模型

Gemini 不止一个型号，我们要挑一个开始用。

方式 A 用户：用 /models 命令交互选

在 OpenCode 输入框里输入：

回车后会弹出模型列表，新手建议这样选：

• 先选 gemini-2.5-flash：速度快、免费额度多，先跑通流程用它最合适
• 等熟悉了、要处理复杂任务时，再换 gemini-2.5-pro（更聪明但额度消耗快）

操作方式：方向键移动 → 回车确认。

方式 B 用户：在配置文件里指定

方式 B 的模型在步骤三 B2 的 defaultModel 字段里已经指定好了，启动 OpenCode 即用，不用再选。想换模型时，改 defaultModel 的值，保存重启即可。

步骤五：发条消息试试

现在一切就绪，发一条消息验证 AI 是否真的能回你。

1. 在输入框打字

在最下面的输入框里打字（就像用微信一样），比如：

2. 按回车发送

按 回车 发送。

3. 查看 AI 回复

如果 Gemini 正常返回了一段自我介绍，恭喜你，接入成功！ 🎉

你也可以看 OpenCode 界面顶部，当前用的模型会显示成 google/gemini-...，证明现在和你聊天的是 Gemini。

场景应用示例

接好之后能干啥？下面是几个常见用法，直接把提示词复制到 OpenCode 输入框发出去就行。

场景1：让 AI 帮你写代码

把这段发给 AI：

AI 会给你：

• 一段可以直接复制运行的完整函数
• 函数参数都加了说明和类型注解
• 附带使用示例和边界处理
• 自动加了错误处理，文件不存在时不会崩溃

场景2：让 AI 解释看不懂的代码

把这段发给 AI：

AI 会给你：

• 一段段拆解每个符号的意思
• 说明它整体在匹配什么样的密码
• 给几个能匹配上、几个匹配不上的例子
• 告诉你它等价的、更易读的写法

场景3：让 AI 帮你修 Bug

把这段发给 AI：

AI 会给你：

• 直接指出问题在哪一行、是什么原因
• 给出修复后的完整代码
• 顺便加上防御性代码，避免以后再犯

最佳实践

提问技巧（让 AI 回答更准）

1. 多给背景：告诉 AI 你在做什么项目、用什么语言，它给的答案更靠谱
2. 分步问：复杂问题拆成几轮，一次只问一个小目标
3. 让它解释：在问题后面加一句「请同时解释原理」，能加深理解
4. 指定格式：明确要求「请输出成 Markdown 表格」「请只给 JSON」，输出更规整

安全习惯

1. 通行证别外传：方式 A 存在 auth.json、方式 B 写在 opencode.json 里的 Key，都是你的私人钥匙，绝不外传、不提交代码仓库（方式 B 务必加 .gitignore）
2. AI 写的代码上线前要检查：AI 偶尔会写错，关键代码务必自己过一遍
3. 控制权限：按最小权限原则配置 API Key 的访问范围
4. 定期换钥匙：每隔几个月回 AI Studio 删旧 Key、生成新 Key，更安全

出错了怎么办

扩展与进阶

还能玩出什么花样

• 加多个 AI 来源：重复跑 /connect 可以把 Claude、OpenAI、本地模型一个个都加进来，之后用 /models 随时切来切去
• 藏起不用的模型：如果模型列表太长眼花，可以在 opencode.json 文件里写一行 whitelist，只保留你常用的几个
• 上下文窗口管理：合理控制对话历史长度，避免超出上下文限制
• 流式输出：OpenCode 默认就是一段段往外蹦字的流式输出，体验接近真人打字
• Function Calling：让 Gemini 调用本地函数，实现更复杂的自动化任务

团队一起用

• 每个人自己 /connect 绑自己的 Key（方式 A），或各自管自己的 opencode.json（方式 B），不要共用一个账号抢额度
• 团队统一默认用 gemini-2.5-flash，复杂任务再切 gemini-2.5-pro
• 方式 B 在团队协作时，建议用密钥管理工具（如 Vault）统一管 Key，别明文写死
• 月底留意免费额度用量，监控 Token 消耗，设置用量告警避免超支