opencode-litellm-gemini-provider

name	opencode-litellm-gemini-provider
description	Configure official native OpenCode to add a local LiteLLM OpenAI-compatible Gemini model as a selectable provider using config-file secret references, without wrappers and without changing the current default model.

OpenCode + LiteLLM Gemini Provider

This skill captures the final, upgrade-friendly way to add a local LiteLLM-routed Gemini model to official OpenCode.

本 Skill 沉淀的是最终采用的、对 OpenCode 官方升级更友好的方案：不改 OpenCode 官方二进制，不使用 wrapper，只通过 OpenCode 原生配置文件把本地 LiteLLM 模型加入 /models，并保持现有默认模型不变。

---

Best Current Approach

Use the official OpenCode binary directly:

~/.opencode/bin/opencode

Configure LiteLLM as a custom OpenAI-compatible provider in:

~/.config/opencode/opencode.json

Store the LiteLLM master key in a local file with 0600 permissions and reference it from OpenCode config using OpenCode's native {file:...} substitution.

核心方案：

• opencode 直接命中官方二进制
• 不把 ~/.opencode/bin/opencode 改成 wrapper
• 不依赖 shell 启动时 export LITELLM_MASTER_KEY
• 不修改顶层 model 字段，因此不改变当前默认模型
• 使用 {file:/path/to/key} 让 OpenCode 自己读取本地密钥文件

---

Bundled Scripts

This skill includes scripts so an agent can reproduce the setup without manually retyping every command.

本 Skill 附带脚本，目标是让从未做过这个配置的 Agent 也能按步骤完成，不只阅读说明。

Scripts:

scripts/setup-native-opencode-litellm.sh
scripts/verify-native-opencode-litellm.sh

Fast Path

From this skill directory:

chmod +x scripts/*.sh
./scripts/setup-native-opencode-litellm.sh
./scripts/verify-native-opencode-litellm.sh

Optional smoke test that sends one real OpenCode request through LiteLLM:

RUN_SMOKE_TEST=1 ./scripts/verify-native-opencode-litellm.sh

Defaults match Toby's local setup:

LITELLM_DIR=$HOME/TobyLab/litellm-vertex-proxy
OPENCODE_CONFIG=~/.config/opencode/opencode.json
OPENCODE_BIN=~/.opencode/bin/opencode
PROVIDER_ID=litellm
MODEL_ID=gemini-3.1-pro-preview
BASE_URL=http://127.0.0.1:4000/v1
KEY_FILE=$LITELLM_DIR/.opencode-litellm-key

If $HOME/TobyLab/litellm-vertex-proxy/scripts/env.sh does not exist but $HOME/GitHub-Codebase/litellm-vertex-proxy/scripts/env.sh does, the setup script uses the GitHub-Codebase path automatically. This keeps the skill usable across Toby's two observed local layouts, including cases where the TobyLab directory exists but is only an empty placeholder.

Override any of them with environment variables:

LITELLM_DIR=/path/to/litellm-proxy \
MODEL_ID=gemini-3.1-pro-preview \
BASE_URL=http://127.0.0.1:4000/v1 \
./scripts/setup-native-opencode-litellm.sh

What the setup script does:

• checks that the official OpenCode binary exists
• sources LITELLM_DIR/scripts/env.sh to read LITELLM_MASTER_KEY
• writes the key to KEY_FILE with 0600 permissions
• backs up an existing opencode.json before editing it
• updates ~/.config/opencode/opencode.json
• adds or replaces only provider.litellm
• does not set top-level model
• does not modify the OpenCode binary
• does not create an opencode wrapper

脚本做的事情：

• 检查官方 OpenCode 二进制是否存在
• 从 LiteLLM 项目的 scripts/env.sh 读取 LITELLM_MASTER_KEY
• 把 key 写入私有文件，并设置 600 权限
• 如果已有 opencode.json，先创建时间戳备份
• 更新 ~/.config/opencode/opencode.json
• 只新增/替换 provider.litellm
• 不设置顶层 model
• 不修改 OpenCode 官方二进制
• 不创建 opencode wrapper

---

When To Use

Use this skill when:

• OpenCode is installed locally and already works with a model such as openai/gpt-5.5
• the user wants to keep official native OpenCode behavior and future opencode upgrade compatibility
• LiteLLM is already deployed locally and exposes an OpenAI-compatible endpoint
• LiteLLM can call Gemini or Vertex AI models such as gemini-3.1-pro-preview
• the user wants Gemini as an additional selectable model, not as a forced default
• the user wants /models to show both ChatGPT/OpenAI models and local LiteLLM models

适用场景：

• 本地已经安装 OpenCode，并且 openai/gpt-5.5 等模型已经可用
• 用户希望尽量使用 OpenCode 官方原生能力，不想用 wrapper 包一层
• 本地已经部署 LiteLLM，且提供 OpenAI-compatible /v1 API
• LiteLLM 已经能调用 Gemini / Vertex AI，例如 gemini-3.1-pro-preview
• 用户只想新增一个模型选项，而不是替换当前默认模型
• 用户希望在 OpenCode TUI 的 /models 中自由切换 OpenAI 与 LiteLLM Gemini

---

Mental Model

OpenCode separates three concerns:

• Program binary: the executable that provides official OpenCode features
• Provider/model registration: the config that determines what appears in /models
• Runtime credentials: the API key used when a selected provider sends a request

The safest setup keeps those concerns separate:

• official binary remains at ~/.opencode/bin/opencode
• provider config lives at ~/.config/opencode/opencode.json
• LiteLLM key lives in a separate private file
• config references that private file with {file:...}
• no wrapper is needed

核心理解：

• ~/.opencode/ 是 OpenCode 程序本体/二进制相关目录
• ~/.config/opencode/ 是 OpenCode 用户配置目录
• 想让模型出现在 /models，改配置即可，不需要改二进制
• 想让 LiteLLM 鉴权成功，配置里的 apiKey 必须能读到 key
• {file:...} 比 wrapper 注入环境变量更适合长期维护

---

Why Not Wrapper As The Primary Solution

Earlier attempts used a wrapper named opencode to source LiteLLM environment variables before executing the real binary. It worked, but it introduced operational risk:

• a wrapper can be shadowed or bypassed by PATH order
• a new terminal may hit the official binary instead of the wrapper
• opencode upgrade can overwrite installation-managed files if the wrapper replaces the official binary
• future troubleshooting becomes confusing because opencode may not be the real executable

The final solution avoids these issues by keeping official OpenCode untouched.

为什么最终不用 wrapper 作为主方案：

• PATH 顺序一变，新窗口可能绕过 wrapper
• wrapper 如果放在 ~/.opencode/bin/opencode，会占用官方安装器管理的路径
• 升级时可能被覆盖，或者让升级排障变复杂
• 原生配置方式更清晰：二进制归 OpenCode 管，模型与密钥归配置管

---

Real Working Setup

The real machine setup that produced this skill:

Official OpenCode binary: /Users/toby/.opencode/bin/opencode
OpenCode config:          /Users/toby/.config/opencode/opencode.json
LiteLLM project:          /Users/toby/TobyLab/litellm-vertex-proxy
LiteLLM API base:         http://127.0.0.1:4000/v1
LiteLLM key file:         /Users/toby/TobyLab/litellm-vertex-proxy/.opencode-litellm-key
LiteLLM model:            gemini-3.1-pro-preview
OpenCode model ID:        litellm/gemini-3.1-pro-preview
Existing OpenAI model:    openai/gpt-5.5

LiteLLM already exposed:

gemini-3.1-pro-preview -> vertex_ai/gemini-3.1-pro-preview
gemini-pro             -> vertex_ai/gemini-3.1-pro-preview
gemini-2.5-pro         -> vertex_ai/gemini-2.5-pro
gemini-2.5-flash       -> vertex_ai/gemini-2.5-flash

Final verification showed:

command -v opencode
=> /Users/toby/.opencode/bin/opencode

opencode models litellm
=> litellm/gemini-3.1-pro-preview

opencode models openai
=> openai/gpt-5.5

---

Step 1: Confirm LiteLLM Works First

Before changing OpenCode, verify the LiteLLM proxy itself.

Example for Toby's local proxy:

cd "$HOME/TobyLab/litellm-vertex-proxy"
source ./scripts/env.sh
curl -sS -H "Authorization: Bearer $LITELLM_MASTER_KEY" "http://${LITELLM_HOST:-127.0.0.1}:${LITELLM_PORT:-4000}/v1/models"

If that directory does not exist, check the common alternate checkout location:

cd "$HOME/GitHub-Codebase/litellm-vertex-proxy"

Expected model list includes:

gemini-3.1-pro-preview

中文说明：先确认 LiteLLM 自己健康，再接 OpenCode。否则后续 Authentication Error 或 model not found 很难判断是 LiteLLM 的问题还是 OpenCode 配置的问题。

---

Step 2: Confirm Official OpenCode Is Being Used

Check path resolution:

command -v opencode
type opencode
file "$HOME/.opencode/bin/opencode"

Desired result:

$HOME/.opencode/bin/opencode
$HOME/.opencode/bin/opencode: Mach-O 64-bit executable arm64

If command -v opencode points to a wrapper such as ~/.local/bin/opencode, disable or rename that wrapper.

Real cleanup command used:

mv /Users/toby/.local/bin/opencode /Users/toby/.local/bin/opencode.wrapper.backup

Then make shell PATH prefer the official OpenCode directory if needed:

export PATH="/Users/toby/.opencode/bin:$HOME/.local/bin:$PATH"

真实排障：之前新窗口报 Authentication Error, No api key passed in，根因是 PATH 命中了错误的入口或没有加载 key。最终方案不再需要 wrapper，所以应确保 opencode 是官方二进制。

---

Step 3: Create A Private Key File For OpenCode

OpenCode supports native file substitution:

{file:/absolute/path/to/secret}

Create a key file that contains only the LiteLLM master key.

Example:

bash -lc 'set -euo pipefail; LITELLM_DIR="$HOME/TobyLab/litellm-vertex-proxy"; [[ -d "$LITELLM_DIR" ]] || LITELLM_DIR="$HOME/GitHub-Codebase/litellm-vertex-proxy"; source "$LITELLM_DIR/scripts/env.sh"; umask 077; printf "%s" "$LITELLM_MASTER_KEY" > "$LITELLM_DIR/.opencode-litellm-key"; chmod 600 "$LITELLM_DIR/.opencode-litellm-key"; test -s "$LITELLM_DIR/.opencode-litellm-key"'

Verify permissions without printing the secret:

LITELLM_DIR="$HOME/TobyLab/litellm-vertex-proxy"
[[ -f "$LITELLM_DIR/.opencode-litellm-key" ]] || LITELLM_DIR="$HOME/GitHub-Codebase/litellm-vertex-proxy"
ls -l "$LITELLM_DIR/.opencode-litellm-key"

Expected shape:

-rw------- ... .opencode-litellm-key

中文说明：

• 这个文件只放 LiteLLM master key
• 不要把 key 打印到聊天、日志、README、commit 或截图里
• 权限用 600
• 如果 LiteLLM master key 以后变更，需要同步更新这个文件

---

Step 4: Configure The LiteLLM Provider In OpenCode

Create or update:

~/.config/opencode/opencode.json

Reference config:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LiteLLM Vertex Proxy",
      "options": {
        "baseURL": "http://127.0.0.1:4000/v1",
        "apiKey": "{file:/Users/toby/TobyLab/litellm-vertex-proxy/.opencode-litellm-key}",
        "timeout": 600000
      },
      "models": {
        "gemini-3.1-pro-preview": {
          "name": "Gemini 3.1 Pro Preview via LiteLLM",
          "family": "gemini",
          "attachment": true,
          "reasoning": true,
          "temperature": true,
          "tool_call": true,
          "limit": {
            "context": 1000000,
            "output": 65536
          },
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

Important details:

• provider.litellm is the provider ID
• the selectable OpenCode model becomes litellm/gemini-3.1-pro-preview
• npm should be @ai-sdk/openai-compatible for LiteLLM's OpenAI-compatible API
• baseURL should include /v1
• apiKey uses {file:...}, not {env:...}
• do not set top-level model unless the user explicitly wants to change the default

中文要点：

• litellm 是 OpenCode 中的 provider ID
• 最终在 /models 里看到的是 litellm/gemini-3.1-pro-preview
• baseURL 是 http://127.0.0.1:4000/v1
• apiKey 通过 {file:...} 读取本地密钥文件
• 不写顶层 model，就不会把默认模型从 openai/gpt-5.5 改成 Gemini

---

Step 5: Verify Both Providers

Run from a fresh shell:

command -v opencode
opencode models litellm
opencode models openai

Expected:

command -v opencode
=> /Users/toby/.opencode/bin/opencode

opencode models litellm
=> litellm/gemini-3.1-pro-preview

opencode models openai
=> openai/gpt-5.5

Optional smoke test:

opencode run -m litellm/gemini-3.1-pro-preview "只回答 OK"

If opencode debug config shows the actual key value, avoid pasting that output into public logs or commits. The key should still not be stored in the config file itself.

Use opencode debug config only when troubleshooting; it may reveal resolved secret values depending on OpenCode version.

中文说明：验证重点是三件事：

• opencode 是官方二进制
• litellm/gemini-3.1-pro-preview 能出现在模型列表里
• openai/gpt-5.5 仍然可见，说明没有破坏原有 OpenAI 模型

---

Step 6: Use In TUI

Launch OpenCode normally:

opencode

Inside the TUI:

/models

Switch between:

openai/gpt-5.5
litellm/gemini-3.1-pro-preview

The selected model applies to the current OpenCode session. Use /models again to switch back.

中文说明：以后就是原生 OpenCode 用法。直接输入 opencode，在 TUI 里用 /models 选择模型。切换到 Gemini 时走本地 LiteLLM；切回 GPT-5.5 时走 OpenAI。

---

Upgrade Behavior

This approach is upgrade-friendly because it does not replace or wrap the official binary.

Future command:

opencode upgrade

can update:

~/.opencode/bin/opencode

The provider config remains in:

~/.config/opencode/opencode.json

So new OpenCode features should remain available through the official binary, and the LiteLLM provider should keep working as long as OpenCode continues supporting custom providers and {file:...} config substitution.

升级影响：

• 官方二进制仍然归 OpenCode 管理
• opencode upgrade 更新官方二进制，不会覆盖你的 provider 配置
• 新版 OpenCode 的官方功能仍然通过原生二进制获得
• 只要 OpenCode 继续支持自定义 provider 与 {file:...}，这个配置就能延续

---

Rollback

To remove the LiteLLM model option:

Remove provider.litellm from ~/.config/opencode/opencode.json

To remove the private key file:

rm /Users/toby/TobyLab/litellm-vertex-proxy/.opencode-litellm-key

To restore a previously disabled wrapper, only if needed:

mv /Users/toby/.local/bin/opencode.wrapper.backup /Users/toby/.local/bin/opencode

中文回滚：

• 删除 opencode.json 里的 provider.litellm 即可让模型从 /models 消失
• 删除 .opencode-litellm-key 即可移除给 OpenCode 用的 LiteLLM key 文件
• 不需要恢复或改动官方 OpenCode 二进制

---

Common Pitfalls

• Do not hardcode the LiteLLM key in opencode.json.
• Do not commit .opencode-litellm-key or any .env file containing secrets.
• Do not set top-level model if the user wants to preserve the default model.
• Use /v1 in baseURL for the OpenAI-compatible provider.
• Confirm the model ID with LiteLLM's /v1/models; do not guess it.
• If Authentication Error, No api key passed in appears, inspect opencode debug config and confirm apiKey resolves through {file:...}.
• If command -v opencode points to ~/.local/bin/opencode, a wrapper may still be shadowing the official binary.
• If zsh PATH puts ~/.local/bin before ~/.opencode/bin, ensure there is no stale ~/.local/bin/opencode wrapper.

常见坑：

• 把 master key 明文写进 opencode.json
• 把 key 文件或 .env 提交到 GitHub
• 写了顶层 model，导致默认模型被改成 Gemini
• baseURL 少了 /v1
• 模型名和 LiteLLM 暴露的模型名不一致
• 旧 wrapper 仍然在 PATH 前面，导致以为自己在用官方二进制，实际不是

---

Historical Alternative: Wrapper Mode

Wrapper mode can still work, but it is no longer the recommended primary solution for OpenCode.

It looked like this:

#!/usr/bin/env bash
set -euo pipefail

source /Users/toby/TobyLab/litellm-vertex-proxy/scripts/env.sh
exec /Users/toby/.opencode/bin/opencode "$@"

Use wrapper mode only when:

• the runtime cannot use {file:...}
• the user explicitly wants environment-variable injection
• the wrapper has a distinct name such as opencode-litellm, not a replacement for official opencode

历史经验：wrapper 可以工作，但它不是最稳的长期方案。优先使用官方二进制 + opencode.json + {file:...}。

---

Final User-Facing Summary Template

English:

OpenCode now uses the official native binary directly. The LiteLLM Gemini model is configured as `litellm/gemini-3.1-pro-preview` through `~/.config/opencode/opencode.json`, with the API key loaded via OpenCode's `{file:...}` secret reference. Start OpenCode with `opencode`, run `/models`, and switch between `openai/gpt-5.5` and `litellm/gemini-3.1-pro-preview`.

中文：

现在使用的是官方原生 OpenCode 二进制，没有 wrapper。LiteLLM Gemini 模型通过 `~/.config/opencode/opencode.json` 配置为 `litellm/gemini-3.1-pro-preview`，API key 由 OpenCode 原生 `{file:...}` 读取。以后直接运行 `opencode`，进入后用 `/models` 在 `openai/gpt-5.5` 和 Gemini 之间切换。