# OpenCode Go Direct Hermes Provider

## Architecture

```
Hermes Agent
    │
    ├── provider: opencode-go
    │   └── base_url: https://opencode.ai/zen/go/v1
    │       └── API key from ~/.local/share/opencode/auth.json
    │           └── "providers" -> "opencode" -> "apiKey"
    │
    └── fallback: openrouter (optional)
```

## Diagnosis Commands

### Verify the API endpoint is reachable

```bash
curl -s --max-time 15 "https://opencode.ai/zen/go/v1/chat/completions" \
  -H "Authorization: Bearer $OPENCODE_GO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.6-plus","messages":[{"role":"user","content":"say OK"}],"max_tokens":5}'
```

Expected success: `{"choices":[{"message":{"content":"OK",...}}],...}`
Failure: `{"type":"error","error":{"type":"ModelError","message":"Model X not supported"}}`

### Discovery: what models does the API actually accept?

The Go API has a working `/v1/models` endpoint at the same base URL:

```bash
curl -s --max-time 10 -H "Authorization: Bearer $OPENCODE_GO_API_KEY" \
  "https://opencode.ai/zen/go/v1/models" \
  | python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin)['data']]"
```

This returns 15 models. You can also probe models individually — useful when the model list disagrees with the Hermes catalog:

```bash
for m in qwen3.6-plus qwen3.5-plus minimax-m2.7 minimax-m2.5 \
         kimi-k2.6 kimi-k2.5 glm-5.1 glm-5 deepseek-v4-pro deepseek-v4-flash \
         mimo-v2.5-pro mimo-v2.5 mimo-v2-pro mimo-v2-omni hy3-preview; do
  echo -n "$m → "
  curl -s --max-time 10 "https://opencode.ai/zen/go/v1/chat/completions" \
    -H "Authorization: Bearer $OPENCODE_GO_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"model\":\"$m\",\"messages\":[{\"role\":\"user\",\"content\":\"OK\"}],\"max_tokens\":3}" \
    | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('choices',[{}])[0].get('message',{}).get('content','ERROR: '+str(d)))"
done
```

### Verify Hermes provider registration

```bash
# Check the key is in .env
grep OPENCODE_GO_API_KEY ~/.hermes/.env

# Check the provider is in config.yaml
grep -A3 'opencode-go:' ~/.hermes/config.yaml

# Smoke test via Hermes CLI
hermes chat -q "say: GO_SMOKE_OK" --provider opencode-go -m qwen3.6-plus
```

### Verify the auth.json key matches what OpenCode CLI uses

```bash
python3 -c "
import json
with open('$HOME/.local/share/opencode/auth.json') as f:
    key = json.load(f)['providers']['opencode']['apiKey']
print(f'Key length: {len(key)} chars, starts with: {key[:8]}...')
"
```

## Known Working Models (as of May 2026)

| Model | Direct API | Notes |
|-------|-----------|-------|
| `qwen3.6-plus` | ✅ | Qwen 3.6 Plus (Go tier) |
| `minimax-m2.7` | ✅ | MiniMax M2.7 (Go tier) |
| `minimax-m2.5` | ✅ | MiniMax M2.5 |
| `kimi-k2.6` | ✅ | Kimi K2.6 |
| `kimi-k2.5` | ✅ | Kimi K2.5 |
| `glm-5.1` | ✅ | GLM 5.1 |
| `glm-5` | ✅ | GLM 5 |
| `deepseek-v4-pro` | ✅ | DeepSeek V4 Pro |
| `deepseek-v4-flash` | ✅ | DeepSeek V4 Flash |
| `mimo-v2.5-pro` | ✅ | MiMo V2.5 Pro |
| `mimo-v2.5` | ✅ | MiMo V2.5 |
| `mimo-v2-pro` | ✅ | MiMo V2 Pro |
| `mimo-v2-omni` | ✅ | MiMo V2 Omni |
| `hy3-preview` | ✅ | Hy3 Preview (not in Hermes catalog) |
| `opencode/big-pickle` | ❌ | CLI-only model, not on direct API |
| `deepseek-v4-flash-free` | ❌ | Not on direct API |
| `opencode/nemotron-3-super-free` | ❌ | Not on direct API |

## Pitfalls

- **Model names differ between CLI and API.** The OpenCode CLI uses `opencode/<name>` prefix; the direct API uses bare names. `opencode/big-pickle` does NOT work through the direct API.
- **The API endpoint path changed once** (was `console.opencode.ai` initially, now `opencode.ai/zen/go/v1`). Check `hermes_cli/auth.py` for the canonical URL if the old one stops working.
- **API keys from `opencode providers login` expire.** If the direct provider starts 401-ing, re-run `opencode providers login --provider opencode` to refresh, then re-copy the key.
- **Hermes treats `opencode-go` as an `is_aggregator` provider.** Models appear without namespace prefix in `/model`. The catalog auto-fetches from Hermes' curated list — the Go API may offer more or fewer models.
- **Free-tier models** (`deepseek-v4-flash-free`, `nemotron-3-super-free`) are not available through the direct API even though `opencode models` lists them.
- **Can't proxy through OpenCode's own custom provider.** Adding the Go API as a custom `@ai-sdk/openai-compatible` provider in `opencode.json` fails with 401 "Invalid API key" even though the same key works via curl. The built-in `opencode` provider also uses `@ai-sdk/openai-compatible` internally, but the Go API checks something beyond the Bearer token (probably User-Agent or request fingerprint). Only Hermes' built-in `opencode-go` provider or plain curl can reach this endpoint directly.
- **`hy3-preview` is not in Hermes' curated catalog.** If the model picker doesn't show it, use `/model opencode-go/hy3-preview` directly — it works.