Docs: opencode config schema fixes — provider (singular), apiKey in options, agent.instructions format

[smallgun01]

Description

Problem

The opencode agent config example in the docs uses providers (plural) and places apiKey/baseUrl at the provider top level. opencode 1.17.x actually expects provider (singular) with apiKey/baseURL inside options.

Three schema mismatches found during ECS Fargate deployment:

1. "providers" → opencode 1.17.x returns Unrecognized key: providers
2. "apiKey" / "baseUrl" at provider top level → silently ignored, API call fails with AI_APICallError: Missing API key
3. "agent": { "instructions": "string" } → returns Expected object, got string

Why It Matters

Anyone following the current docs to deploy opencode-go on openab will get:

• Unrecognized key errors on startup
• Silent API key failures (no error, just fallback to free models)
• ACP Connection Lost with no debug output

Verified on: openab 0.9.0-beta.2-opencode, opencode 1.17.9, ECS Fargate Spot

Current Behavior (from live container)

// ❌ What the docs suggest
{
  "providers": {
    "opencode-go": {
      "baseUrl": "...",
      "apiKey": "..."
    }
  }
}
// Result: Unrecognized key: providers

// ❌ apiKey at top level
{
  "provider": {
    "opencode-go": {
      "apiKey": "...",
      "baseURL": "..."
    }
  }
}
// Result: AI_APICallError: Missing API key (silently ignored)

// ✅ Verified working (opencode debug config output)
{
  "provider": {
    "opencode-go": {
      "options": {
        "baseURL": "https://opencode.ai/zen/go/v1",
        "apiKey": "..."
      },
      "models": {
        "deepseek-v4-flash": {}
      }
    }
  },
  "model": "opencode-go/deepseek-v4-flash"
}

### Suggested Change

Prior Research

• Searched open issues/PRs: no existing reports found
• Code checked: opencode debug config on live container (openab 0.9.0 + opencode 1.17.9)
• External refs: opencode.ai/docs/config

Proposed Fix

Update the opencode config example in docs to use:

1. "provider" (singular)
2. "options": { "baseURL": "...", "apiKey": "..." } (nested)
3. "models": { "model-id": {} } sub-object

[chaodu-agent]

Thanks for the detailed report! I checked the current docs on main and couldn't locate the incorrect example you're referencing:

• docs/opencode.md — uses simple opencode.json with just "model" field
• docs/local-vision-models.md — already uses the correct "provider" (singular) + "options": { "baseURL", "apiKey" } structure

Could you point us to the specific file/page where you saw the wrong "providers" (plural) / top-level apiKey example? A link or file path would help us locate what needs fixing so we can accept a PR.

Also — regarding the "agent": { "instructions": "string" } issue: could you share where that example appears as well?

Thanks!

[smallgun01]

Thanks for checking—you're right, the incorrect schema didn't come from openab docs. We traced our issue to a configuration mistake on our end during deployment.

That said, we'd still like to contribute: the current opencode.md only shows the simple "model"-only config pattern (which works for OAuth providers). For API-key-based providers like opencode-go, users need the full "provider": { ... "options": { "apiKey": "..." } } structure. Would a short example covering this be welcome?

Re: agent.instructions — same suggestion. A note that it expects { "primary": "..." } (not a string) would help.

Happy to open a PR with just the apiKey config example.

Thanks again,

[thepagent]

Happy to open a PR with just the apiKey config example.

Thanks again,

Welcome PR!