Skip to main content

Before you start

Complete organization setup, make sure your account has inference credit, and create a key on the API Keys page. Most coding agents need a tool-capable chat model; Aider’s basic edit workflow does not require native tool calling. Image input and reasoning support depend on the model. These terminal examples use Bash or Zsh on macOS, Linux, or Windows through WSL. Install OpenCode using its official installation guide, then run opencode --version. The config below uses the custom provider format for OpenCode 1.x. Merge the configuration below into your existing config file.

Get your connection settings

Open Integrations, select a model, then choose OpenCode. The screen uses your organization’s region. The examples below use the public global endpoint; replace it with your regional endpoint and replace YOUR_MODEL_ID with the full model ID shown there. Choose one of the models listed for this integration. Set your Pearl API key in the terminal where you run OpenCode:

Configure OpenCode

~/.config/opencode/opencode.json (merge into your existing config)
List your configured Pearl models
Start OpenCode
Copying the configuration from Integrations includes your model’s context and output limits when available. When setting limit manually, include both context and output. Use the selected model’s limits from the model catalog. The model’s options.reasoning.effort sets the default reasoning effort, which OpenCode sends as Pearl’s reasoning object. Don’t use the reasoningEffort option: it sends the flat reasoning_effort field, which Pearl rejects with 400. variants lists the levels the model serves, plus none on models that can turn reasoning off. Keep reasoning_options empty: otherwise OpenCode adds its own variants for some model names (DeepSeek among them), and those send reasoning_effort. Cycle the variants with Ctrl+T in the TUI, or pass --variant to opencode run. Levels the model doesn’t serve round up to the next one it does (see how effort levels map).

Select a Pearl model

OpenCode lists the models you add under provider.pearl.models in your config. To add another Pearl model, add its exact catalog ID to that object and restart OpenCode. Select it with /models or the startup command above. If another endpoint or model is used, check the project’s opencode.json, the .opencode directory, and OPENCODE_CONFIG and OPENCODE_CONFIG_CONTENT. These can override your global configuration. Merge the Pearl provider with your existing providers and preferences.

Start using OpenCode

Open a project folder and start a new conversation. Ask OpenCode to explain a file or make a small change, then approve the file operations you want it to perform. You can review your usage and costs on the Analytics page.

Troubleshooting

  • 401: check the key and allow time for a newly created key to reach the inference gateway.
  • 404: copy the endpoint and exact model ID from Integrations. OpenAI base URLs end in /v1; the Anthropic SDK and Claude Code use the URL without that suffix.
  • 402: check your organization’s credit and billing status.
  • 429 or Anthropic 529: respect retry instructions and reduce concurrency.
  • For truncated output, check the output limit and reasoning budget. Increase limits only within the model’s maximum output length.