Skip to main content

Connect OpenCode

Use a custom provider backed by @ai-sdk/openai-compatible. This guide selects Chat Completions, so choose an eligible model in OpenCode Setup.

Install and configure​

Install OpenCode using its official instructions. For the npm installation:

Shell
npm install -g opencode-ai
export PRIMEX_API_KEY=YOUR_API_KEY

Merge this into your project's opencode.json. Replace both model placeholders with the same exact offering ID. Keep existing provider and project settings.

JSON
{
"$schema": "https://opencode.ai/config.json",
"model": "primex/YOUR_LIVE_CHAT_MODEL",
"provider": {
"primex": {
"npm": "@ai-sdk/openai-compatible",
"name": "Primex",
"options": {
"baseURL": "https://gateway.primexos.com/v1",
"apiKey": "{env:PRIMEX_API_KEY}"
},
"models": {
"YOUR_LIVE_CHAT_MODEL": {"name": "Primex model"}
}
}
}
}

OpenCode resolves {env:PRIMEX_API_KEY} from its process environment. A missing variable becomes empty. Alternatively, /connect → Other can save a credential under provider ID primex; if you use that route, remove the explicit apiKey option so it does not override the saved credential. OpenCode stores those credentials in ~/.local/share/opencode/auth.json.

See Custom providers and configuration variables. Responses adapters, model limits, reasoning options and provider-specific features require separate configuration. Do not copy upstream model defaults or context limits that disagree with the Primex Catalog.

Verify text and an agent turn​

Run opencode, use /models to select the primex model, and send a short text prompt. Then, in a disposable project, ask it to read a harmless file and report its first heading. Review the tool action and confirm that a tool result leads to a final answer. Inspect all requests in Usage.

OpenCode can issue multiple model requests for one task. Set a dedicated key cap and inspect model/tool compatibility before enabling broader actions.

Common fixes and removal​

  • Model missing: the provider ID and both model IDs must match; the config supplies OpenCode's model list independently of gateway discovery.
  • 401: export the environment variable in the shell that launches OpenCode; avoid an empty option overriding saved credentials.
  • Wrong path: this adapter uses /v1/chat/completions; do not use a Responses-only model.
  • Tool/parameter failure: use published model capabilities and disable the unsupported option. Follow Errors & limits.

Remove the primex provider and default-model selection, unset the variable, and remove its saved OpenCode credential if you used /connect. Revoke the Primex key when it is no longer needed.

Need help connecting? Report a setup issue.