OpenCode and Kilo Code both let you add your own OpenAI-compatible provider, and both configs look simple. The part that bit me wasn't the URL or the key. It was a missing limit block that made long sessions fall over an hour in, with no obvious cause.
Here are the configs I use and the mistakes I made getting there. My examples point at APIClaw, an OpenAI-compatible gateway I build, so weigh that accordingly. Swap in any provider's base URL and model IDs.
/v1 (for example https://apiclaw.biz/v1). Don't add /chat/completions; the client adds the path.
export APICLAW_API_KEY="sk-your-key"
OpenCode's provider docs say any OpenAI-compatible API works through the @ai-sdk/openai-compatible package. Put this in ~/.config/opencode/opencode.json (a project-level opencode.json also works):
{
"$schema": "https://opencode.ai/config.json",
"model": "apiclaw/YOUR_MODEL_ID",
"provider": {
"apiclaw": {
"npm": "@ai-sdk/openai-compatible",
"name": "APIClaw",
"options": {
"baseURL": "https://apiclaw.biz/v1",
"apiKey": "{env:APICLAW_API_KEY}"
},
"models": {
"YOUR_MODEL_ID": {
"name": "YOUR_MODEL_ID",
"limit": { "context": 200000, "output": 16384 }
}
}
}
}
}
How the pieces connect:
apiclaw under provider is a provider ID you choose. The top-level model is that ID, a slash, then the model key: apiclaw/YOUR_MODEL_ID. models must match the ID the server returns from GET /v1/models. OpenCode's docs spell out the same rule in their local-server example.{env:APICLAW_API_KEY} reads the variable at runtime.
If you'd rather not use an environment variable, run opencode auth login (or /connect inside OpenCode), choose Other, and enter the same provider ID, apiclaw. That stores the key, but it doesn't ask for a base URL or models, so you still need the opencode.json block. The provider ID you type there has to match the key under provider exactly.
Verify with /models. Your model should be listed under the provider name. Then send a one-line prompt and check the provider's request log.
Kilo Code has two ways in.
VS Code extension: Settings, then the Providers tab, then Custom provider at the bottom. Give it a unique provider ID, choose OpenAI Compatible as the provider API, paste the /v1 base URL and your key, then pick a model from the fetched list or paste the exact ID.
Kilo CLI: the provider block goes in the global ~/.config/kilo/kilo.jsonc:
{
"$schema": "https://app.kilo.ai/config.json",
"model": "openai-compatible/YOUR_MODEL_ID",
"provider": {
"openai-compatible": {
"options": {
"baseURL": "https://apiclaw.biz/v1",
"apiKey": "{env:APICLAW_API_KEY}"
},
"models": {
"YOUR_MODEL_ID": {
"name": "YOUR_MODEL_ID",
"tool_call": true,
"limit": { "context": 200000, "output": 16384 }
}
}
}
}
}
The global file matters. In my setup, {env:...} only resolved from the global config; the same block in a project file silently failed to authenticate. If Kilo says your key is invalid and curl says it's fine, check which file the block is in. kilo models confirms whether the provider loaded.
Both tools know the context window for models in their built-in catalogs. A custom provider's model isn't in that catalog, so the client only knows what you tell it in limit.
Leave limit out and the client doesn't know the context size; in Kilo a custom model with no limit resolves to zero. Compaction (the step where the agent summarizes old turns to make room) never triggers, the conversation keeps growing, and eventually the provider rejects a request for being too long. It looks like a random failure an hour into a session, and it has nothing to do with the provider being flaky.
Set context to the model's real window and output to its real max output tokens, from the vendor's model page. Setting them a bit lower than the real numbers is fine and leaves headroom. Setting them higher than the real numbers brings the same failure back.
Invalid API key / 401. Key pasted with a trailing space, key inactive, or (Kilo) the block is in a project file where {env:...} didn't resolve.
Model not found / 404. The model key isn't the exact server ID, or the base URL is missing /v1 or has /chat/completions on the end.
The model appears but tool calls are ignored. The model doesn't support function calling well, or (Kilo) tool_call isn't set to true on the custom model entry. Try a model known for tool use before blaming the provider.
Long sessions die with a context-length error. Missing or inflated limit. See above.
You need the Responses API. For OpenCode, switch the npm package to @ai-sdk/openai; @ai-sdk/openai-compatible speaks Chat Completions. Only do this if your provider serves /v1/responses.
{env:NAME}. providerid/modelkey. limit.context and limit.output set to the model's real numbers.~/.config/kilo/kilo.jsonc./models (OpenCode) or kilo models (Kilo) shows the model, and a test prompt shows up in the provider's log.
OpenCode's providers page at opencode.ai/docs and Kilo's own docs are the source of truth if the config schema changes.