Repository navigation
custom openai-compatible provider: free-tier models rejected with "free tier can only be used from within OpenCode" even in official OpenCode #56662
Description
Summary
When using a custom openai-compatible provider whose baseURL proxies opencode's free-tier models (e.g. glm-5.3-flash-free), every request fails with Error: OpenCode's free tier can only be used from within OpenCode. Download it at https://opencode.ai and keep building. even though the request is made from the official OpenCode binary.
Environment
- opencode version: v2.0.32
- OS: Linux 7.2.9-2-cachyos, x86_64 (kernel 7.2.9-2-cachyos)
- Terminal: xterm-256color, COLORTERM=truecolor
- Shell: /bin/fish
- Install/channel: latest release
- Active plugins: one local plugin (
~/.config/opencode/plugins/i-have-adhd.js), unrelated to providers
Reproduction
- Configure a custom provider in
opencode.jsonusing@opencode/ai/providers/openai-compatiblewith abaseURLpointing to a third-party gateway that relays opencode free-tier models (model registered asconstellation/glm-5-3-flash-free). - Select that model in the official OpenCode TUI.
- Send any message.
Expected Behavior
The request succeeds, or fails with a clear error explaining which condition failed (e.g. which client identity header/check the server expects).
Actual Behavior
Every request fails with:
Error: OpenCode's free tier can only be used from within OpenCode. Download it at https://opencode.ai and keep building.
Additional Context
- Reproduces consistently, from the official OpenCode binary downloaded from https://opencode.ai.
- The free-tier check appears to be server-side and rejects requests relayed through an openai-compatible gateway, since the upstream request no longer carries the official client identity. The end user is running official OpenCode, but the block still triggers.
- Question: is relaying free-tier models through a custom openai-compatible provider supposed to be blocked? If yes, the error message is misleading (it implies the user is not running OpenCode). If no, the check seems to have a false positive here.
- Workaround: none found besides switching to a non-free model.
Activity
opencode-agent commentedon Oct 18, 2026
Thanks for the detailed report, @yanhenrique-dev!
On your question: the free-tier check runs on OpenCode's server (Zen), not in your client. With a custom openai-compatible provider pointing at a third-party gateway, your OpenCode only talks to that gateway. The gateway is the one that calls the free tier, so the server sees the gateway's request, not your official client. The free tier is meant to be used directly from OpenCode through the built-in
opencodeprovider, so relayed requests are expected to be rejected. To use the free models, select them under the built-inopencodeprovider (e.g.opencode/...-free) instead of through the gateway.You're right that the message is misleading here: it suggests you aren't running OpenCode when the real cause is the relay. I'll treat this as a request for a clearer error that says why the request was rejected, and maintainers will consider it.
Related issues:
opencodeproviderrugabunda commentedon Oct 18, 2026
I hit this too, and I think I found the trigger — it's the request body, not the headers.
Setup: official CLI, opencode 1.19.3 on Windows,
opencode/deepseek-v4.1-flash-free, clean env. It only fails when I have a plugin loaded that rewrites the outgoing chat-completions body (the lazy-load plugin, which strips every tool except its own gateway tool). With that plugin off —--pure— it works fine. Same session id, same everything.Two things worth knowing:
The headers are fine. I logged the actual request the plugin sends and it's a perfectly valid opencode request —
User-Agent: opencode/1.19.3 ...,x-opencode-client,x-opencode-project,x-opencode-request, and a well-formedx-opencode-session(ses_+ 12 hex + 14 base62). It still 403s. So the gate is looking at the body.Specifically
body.tools. If the tool array is a single custom gateway tool, it's rejected. If it still contains the normal built-in opencode tools, it goes through.So for anyone writing a provider proxy or a request-rewriting plugin: keep the built-in tools in
body.toolsand only strip the MCP/custom ones. That fixed it for me — plugin fully active, free model answers normally, and tools still run.One gotcha for whoever tests this: make sure you clear
OPENCODE,OPENCODE_PIDandOPENCODE_PUREfrom the env before the A/B. If you start your shell from a--puresession those are inherited and the plugin silently stays off, which makes it look like it works.Workaround meanwhile: run
--pure, drop the request-rewriting plugin, or point the plugin at a non-gated provider.rugabunda commentedon Oct 18, 2026
Looks like the aforementioned fix was already circumvented by opencode.
opencode-agent commentedon Oct 18, 2026
Thanks for the report. The free models are provided at our own cost, specifically for use inside OpenCode. That's the condition that lets us offer them for free. Routing them through a gateway or relay you run, or using them outside OpenCode, goes against that, so these requests being rejected is intended.
If you want to use models elsewhere, the paid options work differently, since you're covering the usage.
If you're using OpenCode itself, without a relay, and still get this error, that's a separate case. Please open a new issue for it.
Closing this since it's working as intended.