diff --git a/docs/opencode.md b/docs/opencode.md
index b762a0a46..5a40d05f8 100644
--- a/docs/opencode.md
+++ b/docs/opencode.md
@@ -193,6 +193,49 @@ kubectl rollout restart deployment/openab-opencode
 
 > **Important:** Do NOT set a custom `baseURL` or provider override for xAI. The built-in xAI provider handles routing correctly. A stale `~/.config/opencode/opencode.json` with `baseURL: "http://localhost:9090/v1"` (from xai-proxy setups) will break xAI — delete it if present.
 
+## Example: API Key Providers
+
+For providers that use API keys instead of OAuth (e.g. opencode-go, custom
+OpenAI-compatible endpoints), the config needs the full `provider` block with
+`options.apiKey`:
+
+### 1. Set the model and API key
+
+Create `opencode.json` in the working directory (`/home/node`). The key
+difference from OAuth providers is the `provider.options.apiKey` field:
+
+```bash
+kubectl exec -it deployment/openab-opencode -- bash -c 'cat > /home/node/opencode.json << EOF
+{
+  "provider": {
+    "opencode-go": {
+      "options": {
+        "baseURL": "https://opencode.ai/zen/go/v1",
+        "apiKey": "{env:OPENCODE_API_KEY}"
+      },
+      "models": {
+        "deepseek-v4-flash": {}
+      }
+    }
+  },
+  "model": "opencode-go/deepseek-v4-flash"
+}
+EOF'
+```
+
+> Inject `OPENCODE_API_KEY` via a Kubernetes Secret as an environment variable.
+>
+> Note: shell-style `${OPENCODE_API_KEY}` would also work in this specific
+> heredoc (bash expands it before writing), but only here. `{env:VAR}` is the
+> form that works everywhere.
+
+
+### 2. Restart to pick up config
+
+```bash
+kubectl rollout restart deployment/openab-opencode
+```
+
 ## Notes
 
 - **Tool authorization**: OpenCode handles tool authorization internally and never emits `session/request_permission` — all tools run without user confirmation, equivalent to `--trust-all-tools` on other backends.