把 Google Gemini 接入 WorkBuddy 和 Trae：一份不用写代码的小白教程

第一步：获取 Google Gemini API Key

不管用 WorkBuddy 还是 Trae，你都需要先拿到一个 API Key（可以理解为一把"钥匙"，让工具能调用 Google 的 AI 模型）。它免费申请，而且个人日常使用完全够用。

1.1 打开 Google AI Studio

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

注意：你需要一个 Google 账号（就是 Gmail 那个账号）。如果没登录，会提示你先登录。

1.2 创建 API Key

1. 登录后，你会看到 API Key 管理页面
2. 点击 "Create API key"（创建 API 密钥）
3. 选择 "Create API key in new project"（在新项目中创建）
4. 等几秒钟，系统会生成一串很长的密钥，类似 AIzaSyD......xxxxx
5. 立刻复制保存下来！ 这串密钥只显示一次；万一关掉没保存，可以到密钥列表里点 Show 重新查看或重新复制（不用删了重建）

1.3 关于网络问题

Google AI Studio 在国内无法直接访问，你需要使用网络加速工具来打开它并创建 Key。拿到 Key 之后，每次调用 API 同样需要稳定的网络环境——也就是说，你本地运行 WorkBuddy / Trae 的电脑，要能正常访问 generativelanguage.googleapis.com 这个域名，否则会一直超时或报连接错误。

1.4 Gemini API 免费额度

Google 提供免费额度（Free Tier），无需绑卡，用 AI Studio 的 Key 就能用。免费模型包括 gemini-2.5-flash、gemini-2.5-pro、gemini-2.5-flash-lite 等，有每分钟/每天的请求次数上限，但日常写代码、问问题完全够用。具体限额见下文第六节。

第二步：理解一个关键概念 —— OpenAI 兼容接口

Google Gemini 官方提供了 OpenAI 兼容接口，意思是：虽然 Gemini 是 Google 的模型，但它模拟了 OpenAI 的 API 格式。这样 WorkBuddy 和 Trae 就能直接把它当成"OpenAI 格式的模型"来用，不需要额外装任何转换工具或代理。

2.1 记住这两个地址

整个教程里真正要填的地址只有两个层级，别搞混：

这是官方文档给出的真实地址，结尾没有 /v1。网上很多教程让你在末尾加 /v1，那多半会踩坑——因为 Google 这层兼容接口的基路径就是 /v1beta/openai，再加 /v1 反而变成了一个不存在的路径，会直接 404。

不同工具对"地址"的理解不一样，下面分两种情形：

• 情形 A（填根地址）：工具自己会在根地址后面补上 /chat/completions 等路径。WorkBuddy 的 models.json 就属于这种。
• 情形 B（填完整路径）：工具让你直接填到 /chat/completions 这一层。Trae 的"完整 URL"模式就属于这种。

记不住也没关系，下面每一步都直接给了该填的成品字符串。

第三步：在 WorkBuddy 中接入 Gemini

WorkBuddy 通过本地配置文件 models.json 来添加自定义模型。把模型信息写进去，重启客户端即可在模型列表里看到。

3.1 找到 / 创建配置文件

• macOS / Linux：~/.workbuddy/models.json
• Windows：C:\Users\你的用户名\.workbuddy\models.json

如果文件不存在，直接用记事本 / VS Code 新建一个，把下面内容粘进去即可。

3.2 写入 Gemini 配置

用任意文本编辑器打开 models.json，写入以下内容（把 你的GEMINI_API_KEY 换成第一步拿到的密钥）：

[
  {
    "id": "gemini-2.5-flash",
    "name": "gemini-2.5-flash",
    "vendor": "Custom",
    "url": "https://generativelanguage.googleapis.com/v1beta/openai",
    "apiKey": "你的GEMINI_API_KEY",
    "supportsToolCall": true,
    "supportsImages": true,
    "supportsReasoning": true,
    "useCustomProtocol": false
  }
]

如果想同时加上 Pro 版本，在 [] 里用逗号隔开再加一个对象（把 id/name 改成 gemini-2.5-pro，url 保持不变）：

[
  {
    "id": "gemini-2.5-flash",
    "name": "gemini-2.5-flash",
    "vendor": "Custom",
    "url": "https://generativelanguage.googleapis.com/v1beta/openai",
    "apiKey": "你的GEMINI_API_KEY",
    "supportsToolCall": true,
    "supportsImages": true,
    "supportsReasoning": true,
    "useCustomProtocol": false
  },
  {
    "id": "gemini-2.5-pro",
    "name": "gemini-2.5-pro",
    "vendor": "Custom",
    "url": "https://generativelanguage.googleapis.com/v1beta/openai",
    "apiKey": "你的GEMINI_API_KEY",
    "supportsToolCall": true,
    "supportsImages": true,
    "supportsReasoning": true,
    "useCustomProtocol": false
  }
]

字段说明：

· url 填根地址 .../v1beta/openai 即可，WorkBuddy 会自己拼接 /chat/completions，不要在末尾加 /v1 或 /chat/completions
· vendor 写 "Custom"（表示走 OpenAI 兼容协议）
· id 和 name 保持一致，就是你在模型下拉里看到的名字
· supportsImages / supportsToolCall / supportsReasoning 建议都开 true，Gemini 原生就支持这些能力

3.3 让配置生效

修改保存后，完全退出 WorkBuddy 再重新打开（不是关窗口，是在 Dock / 系统托盘里彻底退出进程）。重启后，聊天界面底部的模型下拉里就会出现 gemini-2.5-flash，选中它就能用了。

WorkBuddy 常见问题排查

• 报 404 错误：几乎都是 url 填错。确认是 https://generativelanguage.googleapis.com/v1beta/openai，没有多余的 /v1 或 /chat/completions。
• 报 401 错误：API Key 填错或复制时多了空格/换行，重新复制粘贴一遍。
• 报 400 错误：通常是请求体或模型名问题——确认 id 写的是真实存在的模型名（如 gemini-2.5-flash），不要自己编造。
• 模型列表里看不到：JSON 格式写坏了（少逗号、多逗号、引号用成中文引号）。可以用任意 JSON 校验工具先检查一下；另外确认是彻底退出后重开，而不是仅关窗口。
• 一直超时 / 连不上：本地网络访问不了 generativelanguage.googleapis.com，检查你的网络加速工具是否生效。

第四步：在 Trae 中接入 Gemini

Trae（字节出品的 AI 编程 IDE）原生支持添加自定义模型。下面用官方推荐的方式接入，最稳。

方式一：Trae 原生自定义模型（推荐）

1. 打开 Trae IDE
2. 进入 设置 → 模型（快捷键 Ctrl + , / Mac 上 Cmd + ,），打开模型管理面板
3. 点击 "添加模型"，在弹出的窗口里选择 "自定义配置"
4. API 格式选 "OpenAI Chat Completions 格式"
5. 打开 "完整 URL" 开关，勾选后填写完整接口地址：
   https://generativelanguage.googleapis.com/v1beta/openai/chat/completions
6. 模型 ID 填 gemini-2.5-flash（或 gemini-2.5-pro）
7. API Key 填第一步获取的密钥
8. 点击保存。Trae 会立刻用这个地址探活，连上了模型就加进列表了

如果你不勾选"完整 URL"开关，那就填根地址 https://generativelanguage.googleapis.com/v1beta/openai（Trae 会自己补 /chat/completions）。两种写法二选一，效果一样——记住：根地址不带 /v1，完整地址以 /chat/completions 结尾。

方式二：通过 Cline 插件接入（备选）

如果你的 Trae 版本界面里没有自定义模型入口，可以用 Cline 插件作为替代方案：

1. 在 Trae 的插件市场搜索 "Cline" 并安装
2. 安装完成后，在左侧边栏找到 Cline 图标点进去，点右上角齿轮（设置）
3. 在 API Configuration 中：
   • API Provider 选 "OpenAI Compatible"
   • Base URL 填 https://generativelanguage.googleapis.com/v1beta/openai
   • API Key 填你的密钥
   • Model ID 填 gemini-2.5-flash 或 gemini-2.5-pro
4. 点击 Done 保存，在 Cline 聊天窗口测试

第五步：验证是否成功

最可靠的办法是用命令行直接打一下接口（不需要写代码，复制粘贴即可），确认 Key 和网络都没问题：

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的GEMINI_API_KEY" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{"role":"user","content":"你好，用一句话介绍你自己"}]
  }'

如果返回一段带 "content" 的 JSON，说明 Key 和接口都通了。然后回到 WorkBuddy / Trae，发一条消息测试：

"你好，请用一句话介绍你自己。"

模型正常回复就接入成功。若报错，回头对照上面的"常见问题排查"逐项检查。

可选模型与免费额度

截至 2026 年 7 月，gemini-2.5 系列仍是生产环境稳定版（官方承诺可用到 2026 年 10 月），推荐日常使用。各模型特点：

免费额度（Free Tier，无需绑卡）大致如下：

免费档有每分钟/每天上限，写代码时若短时间疯狂调用可能触发限流（返回 429）。正常人机交互完全够用；如果要跑自动化脚本，建议升级到付费档或控制频率。

想要更强？Google 已放出 gemini-3 系列（如 gemini-3-flash、gemini-3.5-flash 等）预览版，能力更强，但预览版通常需要绑定计费、没有免费档。本教程的 2.5 系列对绝大多数人已经绰绰有余，想尝鲜把上面的模型名换成 3 系即可，接入方式完全一样。

进阶：调节 Gemini 的"思考"（reasoning）

Gemini 2.5 是"会先思考再回答"的推理模型。思考能提升质量，但也会更慢、更费 token。你可以按需调节：

• gemini-2.5-flash：支持用 reasoning_effort 控制思考量，取值 none / low / medium / high。设为 none 可关闭思考，响应最快、最省额度，适合简单任务。
• gemini-2.5-pro：思考能力无法关闭，只能调高调低，不能设 none。

在 WorkBuddy / Trae 的图形界面里，这类参数通常通过"高级设置 / 推理强度"开关控制；若你的版本没有该开关，一般保持默认即可，不影响正常使用。

小提醒：Gemini 的"思考过程"会占用输出 token，免费档要注意别让长思考把额度吃太快。日常问答用 gemini-2.5-flash + 默认或 low 思考，是最省又最稳的组合。

总结

整个流程其实就是三步：

1. 去 Google AI Studio 拿 API Key
2. 在工具里添加自定义模型，填入 Gemini 的 OpenAI 兼容地址 + API Key + 模型名
3. 用 curl 或直接在工具里发条消息验证

两个最关键、最容易写错的地址再贴一遍：

• WorkBuddy models.json 的 url（根地址）：https://generativelanguage.googleapis.com/v1beta/openai
• Trae 完整 URL 模式（完整路径）：https://generativelanguage.googleapis.com/v1beta/openai/chat/completions

记住一句话：根地址不带 /v1，完整地址以 /chat/completions 结尾，就不会踩 404 的坑。