Gemini 4 Hydrogen 怎么接入 Cline 和 OpenCode？

通过 Ofox 使用 Hydrogen 时，选择 OpenAI 兼容供应商，把 Base URL 设为 https://api.ofox.io/v1，发送模型 ID google/gemini-4-hydrogen。Cline CLI 可以直接配置该供应商；OpenCode V2 则要先声明自定义供应商和模型，再选中它。 能回答一段文字只是第一步：编程客户端还需要接收工具调用、读取文件，再把工具结果返回模型。

本文针对 Cline CLI 3.0.74 和 OpenCode V2 2.3.0，资料核对日期为 2026 年 11 月 13 日。我们会区分 Google 原生凭据与 Ofox 凭据，并提供一个小型文件读取任务，让你在接入真实代码仓库前先完成验收。Cline 编辑器扩展有自己的版本与界面；这里的 CLI 命令不代表所有扩展版本都采用同样的配置方式。

本文由 Ofox 发布。我们使用正式发布的客户端连接本地服务，由本地服务提供合成的流式响应。两个客户端都实际读取了测试文件，并返回了文件内容。我们没有执行付费 Hydrogen 请求、验证客户账户，也没有测试模型质量或速度。下面的真实服务验收步骤，需要你用自己的账户与调用路径执行，才能确认端到端可用。

本文链接的 OpenCode、Cline 与 Google 原厂文档为英文。

把供应商、密钥和模型作为一组配置

不要把 Google 模型名称与 Ofox 供应商混用，也不要把 Ofox 密钥填进 Google 供应商。本地模型别名和实际发送到接口的 ID 也不是一回事。

Google 建议新集成使用 Interactions，不代表已有编程客户端的 Google 供应商会自动采用这个 API。不要把 Interactions 端点填入 OpenAI 兼容供应商的 Base URL 字段。Hydrogen API 接入教程解释了这些路径各自的请求与响应格式。

本轮核对的 Ofox catalog 列出了 Hydrogen 的 OpenAI、Gemini 协议支持，以及 Chat Completions 端点。这说明存在可接入的路径，但不能单凭模型列表就证明所有客户端功能、上游工具行为或账户额度都可用。Ofox 密钥的创建和使用见API Key 鉴权说明；消息、流式响应与工具字段见Chat Completions 文档。

安装对应客户端版本，准备一个小项目

OpenCode 的包名很重要。当前官方安装文档使用 @opencode/cli 安装 V2，旧包 opencode-ai 属于 V1。两者都提供 opencode 命令，因此不能仅凭命令名称判断该用哪套配置语法。

以下固定为本文核对过的版本：

npm install -g cline@3.0.74
npm install -g @opencode/cli@2.3.0
cline --version
opencode --version

请先查看官方对你所用操作系统的安装要求。固定版本是为了复现本文步骤，不代表它们会一直是最新版。如果已经使用 OpenCode V1，在更改全局安装前先读V1 到 V2 迁移说明。V2 可能替换现有工作流正在使用的同名命令。

2026 年 11 月 13 日截取的 OpenCode 官方英文文档。截图记录版本边界，不是 Hydrogen 模型测试结果。查看迁移原文。

为第一次工具测试创建独立目录。初始化独立 Git 根目录，也能在客户端查找项目配置时明确项目边界。

mkdir hydrogen-client-check
cd hydrogen-client-check
git init
printf 'Local test marker: HYDROGEN_CLIENT_CHECK_20261113\n' > fixture.txt

开始时让项目里只有这个测试文件。目标是观察一次文件读取，而不是审查大型仓库或批准一连串修改。不要把密钥写进 opencode.json 或提交到版本库；OpenCode 示例从 OFOX_API_KEY 读取密钥。通过你平时使用的本地密钥管理方式设置该变量，不要提交填有真实值的环境文件。

在 Cline CLI 中配置 Hydrogen

Cline 的CLI 参考文档说明了供应商认证与自定义模型选择。使用 Ofox 路径时，按准确的 Base URL 和模型 ID 配置 OpenAI 兼容供应商：

cline auth -p openai \
  -b https://api.ofox.io/v1 \
  -m google/gemini-4-hydrogen \
  -k "$OFOX_API_KEY" \
  --data-dir "$PWD/.cline-hydrogen"

openai 是本轮测试使用的 CLI 供应商参数，保存后类型被规范化为 openai-compatible。自定义数据目录将本次 Cline 测试状态与日常 CLI 状态分开。这个目录应当作为私有本地配置保存，并排除在版本控制之外。命令会把凭据传给客户端，不要把变量展开后的参数复制到日志或截图中。如果更适合你的环境，也可以使用 Cline 的交互式认证。

Base URL 到 /v1 结束，不要再追加 /chat/completions，供应商实现会构造请求路径。本地捕获的请求确实追加了 /chat/completions，并发送配置中的准确模型字符串。

如果改用 Google 原生路径，在另一个数据目录使用 Google 密钥与原生模型 ID：

cline auth -p gemini \
  -m gemini-4-hydrogen \
  -k "$GEMINI_API_KEY" \
  --data-dir "$PWD/.cline-google-hydrogen"

不要给这条命令添加 Ofox Base URL。本轮配置检查中，Cline CLI 3.0.74 拒绝为 gemini 设置自定义 Base URL。使用假密钥可以成功保存原生配置，这只证明 CLI 接受配置，不代表密钥有效或项目已获 Hydrogen 访问权限。第一次原生调用失败时，按Hydrogen 访问教程检查 Google 项目配额和验证要求。

现在从测试文件所在目录启动 Ofox 测试：

cline --data-dir "$PWD/.cline-hydrogen" \
  --auto-approve false \
  "Read fixture.txt using a file tool. Return its exact marker. Do not modify files or run shell commands."

出现提示时，检查并批准预期的文件读取。我们明确设置 --auto-approve false，因为该 CLI 版本默认允许自动批准。这是需要交互的验收任务，不是无人值守作业。后续自动化应当单独定义合适的权限。

如果模型选择列表里没有 Hydrogen，要区分选择列表与服务本身。本轮检查的 Cline 源码模型目录没有 Hydrogen，但 CLI 接受自定义 Hydrogen ID。两件事都不能证明真实服务可用。应填写准确的自定义模型 ID、检查已保存的供应商，并查看第一次真实响应，不要随意选择名称相近的旧模型。编辑器扩展的背景说明见Cline API 配置教程。

在 OpenCode V2 中配置自定义 Hydrogen 供应商

在测试项目中创建 opencode.json，放入下面这份完整的 V2 配置。它采用当前供应商配置与模型配置结构：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ofox-hydrogen/hydrogen",
  "providers": {
    "ofox-hydrogen": {
      "name": "Ofox Hydrogen",
      "env": ["OFOX_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.ofox.io/v1"
      },
      "models": {
        "hydrogen": {
          "modelID": "google/gemini-4-hydrogen",
          "name": "Gemini 4 Hydrogen",
          "limit": {
            "context": 1048576,
            "output": 65536
          },
          "capabilities": {
            "tools": true,
            "temperature": false
          }
        }
      },
      "compatibility": {
        "maxTokensField": "max_tokens"
      }
    }
  },
  "permissions": [
    { "action": "*", "resource": "*", "effect": "deny" },
    { "action": "read", "resource": "*fixture.txt", "effect": "allow" }
  ]
}

这里有三个名字需要分清：

• ofox-hydrogen 是本地供应商键。使用独立名称，可以避免与内置供应商或已有自定义配置混淆。
• hydrogen 是本地模型键，两者组成选择字符串 ofox-hydrogen/hydrogen。
• google/gemini-4-hydrogen 是 modelID，即兼容供应商实际发送给 Ofox 的值。

上下文和输出数值是向客户端描述模型限制，不是授予配额，也不保证每次请求都能用满。Hydrogen 的 1,048,576 token 窗口由输入、思考与输出共享；65,536 token 输出预算包含思考，不只是可见文字。这些不是可以分别用满再相加的独立额度。输出上限也不是目标回答长度。先运行小任务，再检查实际路径返回的用量。

两个兼容性设置值得注意。temperature: false 告诉客户端不要发送该采样参数。maxTokensField: max_tokens 则与 Ofox 文档规定的输出 token 字段一致。没有覆盖时，OpenCode V2 的捕获请求使用 max_completion_tokens；加上后，主请求使用 max_tokens。这里验证的是客户端发送字段的变化，不代表已证明 Ofox 拒绝所有其他别名。

权限规则拒绝其他操作，只允许读取匹配测试文件后缀的路径。它面向只有这个测试文件的项目；通配符也可能匹配其他以 fixture.txt 结尾的路径。这不是操作系统沙箱。在真实仓库中加入编辑或终端权限前，请阅读OpenCode 权限文档。

显式指定配置文件路径，执行测试：

OPENCODE_CONFIG="$PWD/opencode.json" \
  opencode run --standalone --format json \
  --model ofox-hydrogen/hydrogen \
  "Read fixture.txt using a file tool. Return its exact marker. Do not modify files or run shell commands."

本轮验证的 V2 CLI 支持 --standalone。显式配置路径与模型选择，有助于排查继承配置或误用默认模型的问题。保留 JSON 事件输出用于验收；分享前移除凭据及私有路径。

OpenCode 通用 API 配置教程提供了更广泛的供应商配置背景。运行当前示例时，应完整沿用上面的 V2 配置，不要把复数形式的 providers 和 permissions 拼进旧 V1 示例。

验证完整的文件工具调用闭环

预期回答包含 HYDROGEN_CLIENT_CHECK_20261113，但仅有这段文字还不足以证明成功。模型可能直接重复对话历史里的值，没有实际读取文件。检查客户端工具事件，确认以下顺序：

1. 请求使用预期供应商与准确模型 ID。
2. 模型请求调用文件读取工具，目标为 fixture.txt。
3. 客户端执行工具，工具结果包含文件里的标记。
4. 客户端在下一次模型请求中返回工具结果。
5. 模型基于返回结果给出最终回答，没有悬而未决的工具调用或客户端错误。

进一步验收时，可以修改文件中的标记，再启动一个新任务，且不在提示词里写出新值。返回的标记应随之变化。检查文件没有被修改，也没有批准意料之外的操作。这是小型正确性测试，不是衡量 Hydrogen 在真实代码库中实现功能的能力。

发布前的检查仅支持以下结论：

OpenCode 在测试中还发起了一次辅助请求。不要假设一个可见用户任务恰好对应一次计费模型请求。连接真实服务后，应查看真实账户用量。我们没有把本地测试的耗时或合成 token 计数作为性能或账单证据。

Cline 的自定义模型捕获请求没有显式 max_tokens 或 temperature 字段。不要认为保存一个模型名称，就会自动设置与 OpenCode 示例相同的输出上限。开始较大工作负载前，应检查客户端支持的设置与实际请求行为。

排查版本、认证和工具历史错误

每次只改变一个变量。先判断错误发生在加载配置、认证、输出文字，还是回传工具结果阶段。

我们用 V1 加载 V2 权限数组，复现了表格第一项版本错误。升级包与迁移权限策略是不同操作；选对可执行程序，不会自动证明原有项目策略的含义保持不变。

Gemini 的函数调用文档和思考签名文档说明，多轮工具交互需要保留的不只是文字。如果客户端或适配器删除了必需的模型状态，第一轮可能成功，下一轮却失败。可参考Gemini 工具调用缺少思考签名的排查方法。该文解释的是错误模式，不代表已证明这两个客户端在 Hydrogen 上存在这个问题。

Gemini API 报错排查也能帮助区分认证、配额和请求格式错误。该文围绕 Argon 撰写，应对照真实 Hydrogen 响应，不要假设模型特有细节完全通用。不要通过编造签名或悄悄丢弃失败的工具结果来“修复”签名错误。

加入真实编程任务前，保存可复现基线

记录客户端包名和版本、所选供应商、实际模型 ID、Base URL、相关配置、权限规则，以及成功的文件工具调用轨迹。记录中不要包含凭据。说明这是本地合成测试还是真实服务测试，以及额度来自哪个账户。

真实文件测试通过后，再进入小型仓库，让模型只读解释一个函数。然后允许一次可审查的修改，运行项目中相关检查。这样可以把路由与工具传输问题，同模型对代码的判断能力分开。成功读取文件不等于终端操作安全、修改可靠，或兼容所有插件。

更换客户端、供应商或模型版本后，先重跑这个小验收任务。需要检查原始请求时，使用Hydrogen API 教程；需要决定用哪个模型时，参考Carbon、Hydrogen 与 Argon 选型指南。模型选型与某个客户端能否完成工具交互，应当分别判断。