OpenCode: How to build a team of AI agents on any OpenAI-compatible gateway

Chatting with a model quickly hits a ceiling: it cannot see your project, run tests or remember context. That is why everyone is talking about agents. An agent is essentially a model plus a harness: the surrounding framework that provides skills, context, integrations and multi-agent logic. Claude Code and Codex set the standard, but the former is tied to Anthropic models, while the latter remains an OpenAI product. OpenCode offers a third option: an MIT license, 75+ providers, local models through Ollama or vLLM, and the freedom to choose a model for each role.

The article was published on Habr AI and written by an employee of Bothub, so its gateway mention and referral link are promotional. The configuration itself, however, is universal and will work with any OpenAI-compatible endpoint.

Connecting a provider and navigating proxy pitfalls

The current v2 branch is installed with npm i -g @opencode/cli. The older opencode-ai package belongs to the 1.x line, and the two are easy to confuse. Other installation options include brew, bun and the official installation script.

The provider is defined in opencode.json using the @ai-sdk/openai-compatible package: specify the gateway's baseURL and list the model IDs. Rather than putting the key in the configuration or environment variables, the recommended approach is to enter it through opencode auth login. That keeps it out of the project files.

The main practical trap involves proxies. OpenCode runs on Bun, whose native fetch handles HTTP_PROXY and HTTPS_PROXY inconsistently. Installing plugins can produce the error fetch() proxy.url must be a non-empty string: the agent returns a URL object, while fetch expects a string. Bun does not accept socks5://; it requires http://. Even with a correctly configured proxy, NO_PROXY must include localhost and 127.0.0.1, or the interface may get stuck in a loop of its own requests. The simplest solution is to unset all proxy variables and restart the service. Only then does it make sense to assemble the agents.

The agent team and separation of permissions

OpenCode has two types of agents. A primary agent is the one you talk to directly. A subagent runs in a child session with its own context and returns only the result to the main chat. The built-in build and plan agents are primary agents, while general and explore are subagents. You can leave them as they are and simply add your own.

The author created seven roles:

• orchestrator (GPT-6.1 Sol) breaks down tasks and delegates, without writing code itself;
• architect (Gemini 4 Argon) designs modules and data flows;
• coder (Claude Sonnet 5.5) implements changes and keeps diffs minimal;
• reviewer (Claude Opus 5.5) reviews only, without producing patches;
• security (GLM-5.3) looks for vulnerabilities;
• docs (GPT-6 Luna) writes documentation;
• tests (GLM-5.3 Flash) writes tests.

The models are assigned on the principle of using an expensive model where greater intelligence is needed and a cheaper one where it is sufficient. The author emphasizes that the choices are partly subjective: he followed the news and wanted to try different models, including open models.

The central rule is that only coder gets edit: allow. If everyone edits files, the diff grows and it becomes unclear who changed what. Meanwhile, reviewer and security retain bash: allow because they need to run linters, inspect git diff and run tests.

Restrictions enforced by the harness, not the prompt

A model can ignore a prompt instruction saying "do not run git push," especially when the task is ambiguous. A restriction in permission cannot be bypassed. Rules are granular: bash asks for confirmation by default, git status and git diff are allowed, and git commit and git push are blocked. Agents can also be moved out of JSON into markdown files at .opencode/agents/<name>.md: the filename becomes the agent's name, the frontmatter becomes its configuration, and the body becomes its system prompt. This is useful when prompts are long and need version control.

Putting it into practice

If you already use Claude Code or Codex, OpenCode is worth trying at least to compare models on your own tasks in a single day. Take away this principle: one agent has write access, the others advise and review, and critical restrictions are enforced through permissions. Test the specific model lineup on your own code, because the author's choices are based more on impressions than benchmarks. The article does not replace the documentation, but it can save several hours of dealing with common pitfalls.