OpenCode maximaal benut: een technische gids voor AI-engineers

OpenCode is inmiddels meer dan een alternatief voor Claude Code of GitHub Copilot. Het is een open, modulair platform voor AI-assisted software engineering dat je zelf kunt samenstellen. Waar proprietaire tools een kant-en-klaar product leveren, geeft OpenCode je de bouwstenen: meerdere modelproviders, een plugin-ecosysteem, native MCP-ondersteuning, eigen agents, skills en headless execution. De vraag is niet of OpenCode kan wat de concurrentie doet, maar hoe je al die onderdelen zo inricht dat ze samen een betrouwbaar, auditeerbaar en schaalbaar AI-engineering-platform vormen.

In eerdere artikelen behandelden we waarom OpenCode de Linux van agents is en hoe het zich verhoudt tot Claude Code in productiecodebases. Dit artikel is de technische vervolgstap. We behandelen de complete configuratie, het CLI-oppervlak, het plugin-ecosysteem, MCP-servers, agents, skills, permissions en concrete use cases. Het doel is simpel: haal alles uit OpenCode wat erin zit, zonder over-engineering.

1. OpenCode als platform, niet als tool

De meeste gebruikers installeren OpenCode als terminal-tool en starten de TUI. Dat werkt, maar het is maar een klein deel van het verhaal. OpenCode is ontworpen als een laag tussen jouw codebase en een willekeurige LLM-backend. Die laag bestaat uit:

• Een CLI met TUI en non-interactive modus
• Een server (opencode serve) voor API-toegang
• Een web interface (opencode web)
• Een ACP-server (opencode acp) voor agent-client-protocollen
• Een plugin-runtime voor JS/TS-plugins
• Een MCP-client voor externe tools
• Een agent-runtime voor subagents met eigen permissies

Dat betekent dat je OpenCode kunt inzetten als persoonlijke coding assistant, als headless agent in CI/CD, als backend voor een eigen tool of als onderdeel van een groter agentic platform. De architectuur is hetzelfde in alle scenario's: prompts, tool calls en context worden lokaal beheerd, de LLM zelf is verwisselbaar.

De filosofie is vergelijkbaar met die van Linux of Kubernetes: een dunne, goed gedefinieerde abstractielaag die je zelf verder invult. Dat vraagt meer configuratie dan een proprietaire tool, maar geeft ook controle over data residency, modelkeuze, audit logging en exitstrategie. Voor organisaties die werken aan soevereine AI-architecturen, zoals we die binnen DjimIT ondersteunen, is dat geen luxe maar een vereiste.

2. Installatie en eerste configuratie

De snelste installatie verloopt via het installatiescript:

curl -fsSL https://opencode.ai/install | bash

Na installatie start je OpenCode met opencode. De eerste keer kun je providers configureren via:

opencode auth login

Dit commando gebruikt de providercatalogus op models.dev. OpenCode ondersteunt daarmee tientallen providers, van OpenAI en Anthropic tot Ollama, LiteLLM-proxies en gespecialiseerde gateways. Credentials worden opgeslagen in ~/.local/share/opencode/auth.json. Je hoeft die file nooit handmatig aan te passen; gebruik altijd opencode auth login en opencode auth logout.

De centrale configuratie staat in opencode.json. Je kunt deze globaal plaatsen in ~/.config/opencode/opencode.json of per project in .opencode/opencode.json. Projectconfiguratie heeft voorrang op globale configuratie.

Configuratie-overerving en omgevingsvariabelen

OpenCode laadt configuratie in een bepaalde volgorde:

1. Standaardwaarden uit de binary
2. Globale ~/.config/opencode/opencode.json
3. Project-specifieke .opencode/opencode.json
4. Omgevingsvariabelen met het prefix OPENCODE_
5. Inline config via OPENCODE_CONFIG_CONTENT
6. Command-line flags

Later geladen bronnen overschrijven eerdere bronnen. Dat betekent dat je een basisconfig in je home directory kunt zetten en per project alleen de afwijkingen definieert. Voor gevoelige waarden zoals API keys gebruik je omgevingsvariabelen of de auth-file, nooit hardcoded keys in opencode.json.

Belangrijke omgevingsvariabelen:

export OPENCODE_CONFIG=/path/to/opencode.json
export OPENCODE_CONFIG_DIR=/path/to/config-dir
export OPENCODE_PERMISSION='{"edit":"deny"}'
export OPENCODE_DISABLE_DEFAULT_PLUGINS=1
export OPENCODE_DISABLE_AUTOCOMPACT=1
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=1
export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=1
export OPENCODE_EXPERIMENTAL_PLAN_MODE=1

Deze variabelen zijn vooral handig in CI/CD of wanneer je snel wilt schakelen tussen verschillende governance-modi zonder config-files te wijzigen.

Een volledige basisconfig ziet er zo uit:

{
  "$schema": "https://opencode.ai/config.json",
  "username": "dennis",
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "openai/gpt-4.1-mini",
  "default_agent": "default",
  "shell": "/bin/zsh",
  "logLevel": "INFO",
  "share": "disabled",
  "autoupdate": "notify",
  "snapshot": true,
  "instructions": ["AGENTS.md", "docs/style.md"],

  "skills": {
    "paths": [".opencode/skills", "~/.config/opencode/skills"],
    "urls": []
  },

  "plugin": [
    "opencode-gemini-auth",
    ["opencode-token-tracker", { "toast": true }],
    "./.opencode/plugins/local-plugin.ts"
  ],

  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp"],
      "enabled": true,
      "env": {}
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  },

  "permission": {
    "edit": "ask",
    "bash": { "git *": "allow", "npm test": "allow", "*": "ask" },
    "skill": {
      "*": "ask",
      "security-review": "allow"
    }
  },

  "experimental": {
    "mcp_timeout": 30000,
    "primary_tools": ["edit", "bash", "read"]
  }
}

Let op de volgende velden:

• model en small_model: het primaire model en een goedkoper, sneller model voor kleine taken.
• instructions: een lijst van bestanden die als systeeminstructie worden meegeladen.
• plugin: npm-packages, lokale bestanden of tuples met opties.
• mcp: externe MCP-servers die als tools beschikbaar komen.
• permission: deny-by-default of ask-by-default per tool-categorie.
• experimental: vlaggen voor nieuwe features.

3. Provider-agnostisch model routing

Een van de sterkste eigenschappen van OpenCode is dat je wisselt van model zonder je workflow te veranderen. De model-string heeft altijd de vorm provider/model-id. Voorbeelden:

{
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "openai/gpt-4.1-mini"
}

Om te zien welke modellen beschikbaar zijn:

opencode models
opencode models anthropic --verbose
opencode models --refresh

De --refresh vlag haalt de laatste modelcatalogus op bij models.dev. Dat is handig als er nieuwe modellen zijn toegevoegd of als je een eigen LiteLLM-proxy gebruikt.

Eigen providers en LiteLLM

Voor organisaties die een interne AI-gateway gebruiken, kun je een LiteLLM-proxy of een andere OpenAI-compatibele endpoint inzetten. Plugins zoals opencode-litellm detecteren automatisch een lopende LiteLLM-proxy op bekende poorten (4000, 8000, 8080) en registreren alle beschikbare modellen:

{
  "plugin": ["opencode-litellm"]
}

Als je liever handmatig configureert, voeg je een provider toe in opencode.json:

{
  "provider": {
    "workstation-litellm": {
      "options": {
        "apiKey": "{env:LITELLM_API_KEY}",
        "baseURL": "http://192.168.1.28:4000/v1"
      }
    }
  },
  "enabled_providers": ["workstation-litellm"],
  "disabled_providers": ["openai"]
}

Dit is exact het patroon dat we binnen DjimIT toepassen: een interne LiteLLM-proxy op de workstation routeert naar verschillende upstreams, afhankelijk van beschikbaarheid, kosten en data-residency. OpenCode praat alleen met die proxy. Zo houd je het control plane centraal en blijft de client dun.

Lokale modellen via Ollama

Voor volledig lokale inference start je Ollama:

ollama pull qwen2.5-coder:14b
ollama serve

En configureer OpenCode:

{
  "model": "ollama/qwen2.5-coder:14b"
}

OpenCode detecteert Ollama automatisch als de standaard endpoint (http://localhost:11434) bereikbaar is. Voor een air-gapped setup wijzig je de Ollama-url via omgevingsvariabelen of een provider-alias.

Modelvarianten en reasoning effort

Sommige providers ondersteunen reasoning-effort varianten, zoals anthropic/claude-sonnet-4-6:thinking. Je kunt deze op drie manieren gebruiken:

1. In opencode.json als model string:

   { "model": "anthropic/claude-sonnet-4-6:thinking" }
   

2. Via CLI flag:

   opencode run --variant thinking "Explain this algorithm"
   

3. Via plugin of agent config:

   {
     "agent": {
       "deep-thinker": {
         "model": "anthropic/claude-sonnet-4-6:thinking"
       }
     }
   }
   

Voor taken die veel redeneren vereisen, zoals architecture reviews of complexe refactors, is een thinking-variant vaak de moeite waard. Voor eenvoudige edits gebruik je het standaardmodel of het small_model om kosten te drukken. Een goede agent-configuratie koppelt het juiste model aan het juiste type taak.

4. Native CLI: meer dan een TUI

De TUI is het meest zichtbare deel van OpenCode, maar de CLI heeft een breed commandoset die je in scripts, CI/CD en automatisering kunt gebruiken.

Non-interactive uitvoering

opencode run "Refactor de auth middleware naar een aparte service"

Dit is vergelijkbaar met claude -p. Je kunt een model, agent en bestanden meegeven:

opencode run -m anthropic/claude-sonnet-4-6 \
             --agent reviewer \
             -f src/auth.ts \
             "Review deze file op OWASP-top-10 risico's"

Headless server

opencode serve --port 4096 --hostname 0.0.0.0

Daarna kun je een TUI of run-oproep koppelen:

opencode attach http://localhost:4096
opencode run --attach http://localhost:4096 "Explain this codebase"

Dit voorkomt dat MCP-servers en het model elke keer opnieuw opstarten. Voor productieachtige agent-workflows is dit essentieel.

Web interface

opencode web --port 4096

Start een webserver met een browserinterface. Handig voor gebruikers die de TUI niet willen of kunnen gebruiken.

Agent management

opencode agent list
opencode agent create --description "Security reviewer" \
                       --mode subagent \
                       --permissions read,grep,bash \
                       --model anthropic/claude-sonnet-4-6

Agents worden opgeslagen als .md-bestanden in .opencode/agent/ of ~/.config/opencode/agent/. Je kunt ze in een repo committen zodat teamgenoten dezelfde agents gebruiken.

MCP management

opencode mcp add
opencode mcp list
opencode mcp auth github
opencode mcp logout github
opencode mcp debug github

De mcp subcommando's maken het eenvoudig om externe tools toe te voegen zonder handmatig JSON te bewerken.

Session management

opencode session list
opencode session list -n 10
opencode export <session-id>
opencode import session.json

Sessions zijn bruikbaar voor audit, debugging en het herstarten van langlopende taken.

Statistieken

opencode stats --days 7 --models --tools

Geeft een overzicht van gebruik per model, tool en project.

Sessie-continuiteit, export en import

Langlopende taken worden vaak onderbroken door contextcompaction, sessie-timeouts of een herstart. OpenCode biedt enkele mechanismen om dit op te vangen:

• --continue of -c: vervolg de laatste sessie.
• --session <id>: vervolg een specifieke sessie.
• --fork: maak een vertakte sessie bij voortzetting.
• opencode export <session-id>: exporteer een sessie naar JSON.
• opencode import <file>: importeer een sessie of een OpenCode share URL.

Voor een handoff tussen sessies kun je een plugin zoals opencode-handoff gebruiken, of je eigen agent instrueren om een continue.md te schrijven. Dat is vooral waardevol in combinatie met spec-driven development: de agent bewaart de huidige staat in een gestructureerd bestand zodat een volgende sessie direct verder kan.

# Sla huidige staat op voor later
opencode -p "Write a concise handoff summary to continue.md"

# Volgende sessie verdergaan
opencode -c

5. Projectinstructies met AGENTS.md

OpenCode leest bij het opstarten automatisch AGENTS.md in de projectroot. Dit bestand bevat projectcontext die het model nodig heeft: conventies, build-commando's, testinstructies, architectuurregels en security-baseline. In tegenstelling tot een losse prompt in de TUI, blijft AGENTS.md persistent en reproduceerbaar.

Een goede AGENTS.md bevat:

• Stack en runtime
• Build-, test- en lint-commando's
• Naamgevingsconventies
• Belangrijke files en waarom
• Veilige en onveilige patronen
• Review- en approval-cultuur

Voorbeeld:

# AGENTS.md - Project Alpha

## Stack
- Next.js 15 App Router
- TypeScript 5.7
- Tailwind CSS v4
- SQLite via better-sqlite3

## Commands
- `npm run dev` - start dev server
- `npm run build` - productiebuild
- `npm run lint` - ESLint
- `npm test` - Vitest

## Conventies
- Gebruik async/await, geen callbacks
- Database queries lopen via `src/lib/db.ts`
- Geen `any`; liever `unknown` met type guards
- Geen secrets in code; gebruik `src/lib/env.ts`

## Security
- Valideer alle gebruikersinput met Zod
- Auth-wijzigingen vereisen menselijke review
- Geen shell commands met gebruikersinput

Je kunt meerdere instructiebestanden laden via instructions in opencode.json:

{
  "instructions": ["AGENTS.md", "docs/api-conventions.md", "docs/security.md"]
}

OpenCode leest ook .claude/CLAUDE.md en .claude/skills indien aanwezig. Dat maakt migratie van Claude Code naar OpenCode eenvoudiger, maar voor nieuwe projecten raden we aan om AGENTS.md en .opencode/skills/ als canonical instructielaag te gebruiken.

6. Het plugin-ecosysteem

OpenCode heeft een groeiend ecosysteem van plugins. De verzameling staat op awesome-opencode/awesome-opencode. Plugins zijn JS/TS-modules die hooks, tools, events en UI-extensies toevoegen. Je laadt ze in via opencode.json:

{
  "plugin": [
    "opencode-agent-memory",
    "opencode-google-ai-search-plugin",
    "opencode-token-tracker",
    ["opencode-bar", { "option": "value" }],
    "./.opencode/plugins/my-local-plugin.ts"
  ]
}

Plugins kunnen op drie manieren worden geïnstalleerd:

1. npm: package naam, optioneel met versie (opencode-foo@1.2.3)
2. lokaal project: ./.opencode/plugins/local.ts
3. globaal: ~/.config/opencode/plugins/local.ts

OpenCode installeert npm-plugins automatisch met Bun bij de volgende start. Er is geen aparte npm install nodig.

Aanbevolen plugins per doel

Persistent memory

• opencode-agent-memory: Letta-style editable memory blocks
• opencode-mem: vector-based persistent memory
• opencode-handoff: sessie-overdracht prompts

Observability en kosten

• opencode-token-tracker: toasts met tokens, kosten en latentie
• opencode-quota: quota en token usage tracking
• opencode-telemetry: lokale SQLite telemetry

Research en web

• opencode-google-ai-search-plugin: Google AI Mode als tool
• opencode-litellm: auto-discovery van LiteLLM-modellen

Orchestratie

• oh-my-opencode: multi-agent orchestratie met Sisyphus, Oracle, Librarian
• opencode-background-agents: async agent delegatie
• opencode-workspace: bundled multi-agent harness

Productiviteit

• opencode-autotitle: AI-generated sessienamen
• opencode-snippets: inline text expansion
• opencode-command-inject: auto-discover Makefile/npm scripts

Security

• envsitter-guard: blokkeert .env leesacties
• opencode-log-sanitizer: redacteert JWTs en base64 in prompts

Let op: begin met één plugin tegelijk. Te veel plugins laden het contextvenster en verhogen de kans op conflicten.

Voorbeeld: agent memory

{
  "plugin": ["opencode-agent-memory"]
}

Na herstart kun je vragen stellen als:

opencode -p "What did we decide about the login refactor?"

De plugin haalt relevante geheugenblokken op en injecteert ze in de context. Dit is vooral waardevol bij het wisselen tussen sessies of taken.

Voorbeeld: web research inline

{
  "plugin": ["opencode-google-ai-search-plugin"]
}

Daarna:

opencode -p "Summarize open CVE fixes for Spring Boot 3.3"

De plugin voegt een search-tool toe die de agent zelf kan aanroepen. Je hoeft geen browser-tab meer open te houden.

Voorbeeld: multi-agent orchestratie

{
  "plugin": ["oh-my-opencode"]
}

Oh My OpenCode voegt meerdere agents toe, waaronder Sisyphus voor grote refactors:

opencode --agent sisyphus -p "Split auth service out of monolith"

De agent plant, coördineert subagents, gebruikt LSP/AST-tools en houdt rekening met de repository-structuur.

7. MCP-servers als verlengstuk

Model Context Protocol (MCP) is het standaardprotocol waarmee OpenCode externe tools benadert. In plaats van elke integratie in de core op te nemen, praat OpenCode met MCP-servers voor GitHub, databases, browsers, zoekmachines, documentatie en meer.

Een lokale MCP-server in opencode.json:

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp"],
      "enabled": true,
      "env": { "BROWSER": "chromium" }
    }
  }
}

Een remote MCP-server:

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Je kunt individuele MCP-tools uitschakelen via tools:

{
  "tools": {
    "playwright": false
  }
}

Dit is nuttig als een MCP-server te veel of te weinig tools exposeert, of als je bepaalde acties wilt blokkeren zonder de hele server uit te zetten.

Een eigen MCP-server maken

Als je een specifieke interne API of database wilt ontsluiten, kun je zelf een MCP-server bouwen. Het protocol is simpel: stdin/stdout JSON-RPC met een aantal gedefinieerde methoden. Een minimale server in Node.js:

// mcp-server.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server(
  { name: "my-internal-api", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "lookup_customer",
      description: "Look up a customer by ID",
      inputSchema: {
        type: "object",
        properties: {
          customerId: { type: "string" }
        },
        required: ["customerId"]
      }
    }
  ]
}));

server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;
  if (name === "lookup_customer") {
    const data = await fetchCustomer(args.customerId);
    return { content: [{ type: "text", text: JSON.stringify(data) }] };
  }
  throw new Error(`Unknown tool: ${name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

Registreer in opencode.json:

{
  "mcp": {
    "my-api": {
      "type": "local",
      "command": ["node", "./mcp-server.js"]
    }
  }
}

Hiermee kun je interne systemen veilig beschikbaar maken voor agents zonder directe database-toegang of shellrechten te geven.

Veilige MCP-praktijken

• Pin MCP-packages op een specifieke versie in command.
• Review de bron van elke MCP-server voordat je deze inschakelt.
• Beperk de omgevingsvariabelen die een MCP-server ontvangt.
• Gebruik tools om ongewenste tools per server uit te schakelen.
• Log welke MCP-calls worden gedaan voor audit.

Voor organisaties die met OpenSpec werken, zoals we bij DjimIT doen, is het raadzaam om MCP-configuratie onderdeel te maken van de infrastructuur-as-code. Zo blijft de toolketen reproduceerbaar en reviewbaar.

MCP voor documentatie en codebase search

Een krachtig patroon is het koppelen van OpenCode aan een codegraph of documentatie-MCP. De Code Review Graph (CRG) die we in deze workspace gebruiken, indexeert bijvoorbeeld functies, klassen, flows en communities. Door deze als MCP te ontsluiten, kan de agent impact-analyses doen zonder de hele codebase te hoeven lezen.

{
  "mcp": {
    "crg": {
      "type": "local",
      "command": ["bun", "x", "@djimit/crg-mcp"],
      "enabled": true
    }
  }
}

De agent kan dan vragen stellen als:

• "Welke functies worden aangeroepen door de login flow?"
• "Wat is de impact radius van een wijziging in src/auth.ts?"
• "Welke tests dekken deze code?"

Dit soort gestructureerde context is vaak efficiënter dan het model zelf grote hoeveelheden code te laten doorzoeken. Het verlaagt tokengebruik en vergroot de reproduceerbaarheid van antwoorden.

8. Eigen agents en subagents

Agents in OpenCode zijn gedefinieerde persona's met eigen model, instructies en permissies. Je kunt ze aanmaken via opencode agent create of handmatig als .md-bestand in .opencode/agent/.

Een agent-definitie ziet er zo uit:

---
model: anthropic/claude-sonnet-4-6
mode: subagent
description: Security-focused code reviewer
permission:
  read: allow
  grep: allow
  bash: deny
  edit: deny
---

You are a security reviewer. Analyze code for OWASP Top 10 risks,
input validation gaps, secret exposure and insecure dependencies.
Do not modify files. Report findings in Dutch with file:line references.

Modes:

• all: agent kan alles doen wat de gebruiker kan doen
• primary: hoofdagent in een sessie
• subagent: agent aangeroepen via het Task-tool, met beperkte rechten

Je start een specifieke agent met:

opencode --agent reviewer
opencode run --agent reviewer -f src/auth.ts "Review this file"

Background subagents

Experimenteel ondersteunt OpenCode background subagents. Deze draaien asynchroon en sturen een notificatie bij voltooiing. Gebruik dit voor onafhankelijk onderzoek of taken die lang duren:

opencode run "Research Kubernetes Gateway API patterns" --background

Dit voorkomt dat je sessie blokkeert terwijl de agent onderzoek doet.

9. Skills: herbruikbare kennis en workflows

Skills zijn herbruikbare instructieblokken die je in .opencode/skills/ of ~/.config/opencode/skills/ plaatst. Ze volgen de Anthropic Agent Skills-specificatie en kunnen worden gedetecteerd door plugins zoals opencode-agent-skills.

Een skill-bestand security-review.skill.md:

---
id: security-review
description: Perform a security review on a codebase
---

## Steps
1. List all entry points in `src/app` and `src/pages`.
2. Check input validation boundaries.
3. Review auth and session handling.
4. Inspect dependency tree for known CVEs.
5. Report findings with severity and remediation.

Configureer de skill-paden in opencode.json:

{
  "skills": {
    "paths": [".opencode/skills", "~/.config/opencode/skills"],
    "urls": ["https://example.com/.well-known/skills/"]
  }
}

Je kunt permissies per skill instellen:

{
  "permission": {
    "skill": {
      "*": "ask",
      "security-review": "allow",
      "internal-*": "deny"
    }
  }
}

Skills zijn ideaal voor herhaalde taken die een vaste aanpak vereisen: security reviews, dependency upgrades, release-checklists of compliance-audits. Voor DjimIT-projecten maken we vaak een skill-set die aansluit op het OpenSpec-change-proces, zodat agents hetzelfde reviewritme volgen als menselijke reviewers.

10. Permissions en security

OpenCode heeft een uitgebreid permissiemodel. Je kunt rechten per categorie instellen: edit, bash, read, glob, grep, webfetch, task, todowrite, websearch, lsp en skill.

Voorbeeld:

{
  "permission": {
    "edit": "ask",
    "bash": {
      "git *": "allow",
      "npm test": "allow",
      "npm run lint": "allow",
      "*": "ask"
    },
    "webfetch": "deny",
    "task": "allow"
  }
}

Dit geeft aan:

• edit: vraag altijd toestemming voor bestandswijzigingen
• bash: alleen git, npm test en npm run lint zonder toestemming; overige commando's vragen
• webfetch: nooit toestaan
• task: subagents mogen draaien

Security-baseline voor productiegebruik

1. Start met edit: ask en bash: ask.
2. Beperk shell-commando's tot een expliciete allowlist.
3. Schakel webfetch en websearch uit als je geen externe research nodig hebt.
4. Gebruik permission.skill om onbekende skills te blokkeren.
5. Zet share: disabled tenzij je expres sessies wilt delen.
6. Draai in een container of VM met least privilege.
7. Configureer egress-allowlisting op netwerkniveau.

OpenCode geeft je de bouwstenen voor een veilig control plane, maar het bouwen van dat control plane blijft jouw verantwoordelijkheid. Dat is precies waarom we binnen DjimIT OpenSpec gebruiken voor materiële wijzigingen: elke configuratieverandering doorloopt een review- en approval-ritueel.

OpenSpec, Open Knowledge Framework en OpenCode

OpenCode is een sterk technisch platform, maar het wordt pas enterprise-waardig als je governance-protocollen eromheen legt. Binnen DjimIT gebruiken we twee eigen frameworks die hier naadloos op aansluiten.

OpenSpec is ons change-control-kader voor materiële wijzigingen. Denk aan infrastructuur, auth, crypto, Docker, systemd, model routing en productie-deployments. Een OpenCode-configuratie die een nieuwe provider toevoegt, een MCP-server inschakelt of brede shellrechten geeft, valt onder dit kader. De workflow is:

1. Proposal in ~/openspec/changes/
2. Risico-inschatting (Critical / High / Medium / Low)
3. Review en approval (Critical/High: expliciete user approval; Medium: auto-approved als OpenSpec change bestaat)
4. Implementatie
5. Archivering

Door OpenCode-wijzigingen via OpenSpec te laten lopen, zorg je dat agent-configuratie hetzelfde reviewritme kent als infrastructuurcode. Dat voorkomt dat een handige agent-setup ongemerkt een productierisico wordt.

Open Knowledge Framework (OKF) is onze aanpak voor het structureren van domeinkennis. In plaats van elke keer de hele context in een prompt te stoppen, slaan we kennis op in atomic notes, scenario's en capability-registers. OpenCode kan deze kennis opvragen via een Knowledge MCP of via references in opencode.json:

{
  "references": {
    "compliance": {
      "path": "~/openspec/specs/compliance",
      "description": "Use for BIO2, EU AI Act and NIS2 compliance decisions"
    },
    "architecture": {
      "repository": "djimit/architecture-decisions",
      "branch": "main",
      "description": "Use for ADRs and architecture constraints"
    }
  }
}

Op deze manier werkt OpenCode niet met losse prompts, maar met een gecureerde kennislaag. Dat is essentieel voor consistente output in gereguleerde of complexe organisaties.

11. Concrete use cases

Use case 1: soevereine ontwikkelomgeving

Stel je werkt aan een overheidspartij of vitale infrastructuur. Data mag niet naar buiten. Je configureert:

{
  "model": "ollama/qwen2.5-coder:14b",
  "share": "disabled",
  "permission": {
    "edit": "ask",
    "bash": { "git *": "allow", "npm test": "allow", "*": "ask" },
    "webfetch": "deny",
    "websearch": "deny"
  },
  "mcp": {},
  "plugin": []
}

OpenCode draait volledig lokaal. Er is geen externe API, geen cloud, geen telemetry. De audit trail zit in je eigen filesystem.

Use case 2: interne AI-gateway

Een enterprise gebruikt een centrale LiteLLM-proxy met SSO, rate limiting en audit logging:

{
  "model": "workstation-litellm/coding",
  "small_model": "workstation-litellm/fast",
  "provider": {
    "workstation-litellm": {
      "options": {
        "baseURL": "http://192.168.1.28:4000/v1",
        "apiKey": "{env:LITELLM_API_KEY}"
      }
    }
  },
  "enabled_providers": ["workstation-litellm"],
  "disabled_providers": ["openai", "anthropic"]
}

Alle verzoeken lopen via de interne gateway. De organisatie bepaalt welke modellen beschikbaar zijn, hoeveel ze kosten en waar data heen gaat.

Use case 3: CI/CD agent

Gebruik OpenCode headless in een pipeline:

# .github/workflows/opencode-review.yml
name: OpenCode Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install OpenCode
        run: curl -fsSL https://opencode.ai/install | bash
      - name: Run security review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          opencode run \
            --agent security-reviewer \
            -f ${{ github.event.pull_request.diff_url }} \
            "Review this PR for security risks"

De agent draait zonder TUI, gebruikt een gedefinieerde agent en produceert een rapport. Je kunt de output naar een comment of artifact schrijven.

Use case 4: multi-file refactor met planning

Voor grote wijzigingen gebruik je plan mode of een orchestratie-plugin:

opencode --agent sisyphus -p "Migrate all API routes from pages router to app router"

Sisyphus maakt een plan, deelt het op in subtaken, start subagents en valideert tussentijds. Dit is geen magie: je blijft reviewen en goedkeuren, maar de coördinatie gebeurt gestructureerd.

Use case 5: kennisgestuurde ontwikkeling

Koppel OpenCode aan een kennisbron via MCP:

{
  "mcp": {
    "knowledge": {
      "type": "remote",
      "url": "http://192.168.1.28:8007/sse",
      "headers": { "Authorization": "Bearer {env:KNOWLEDGE_MCP_TOKEN}" }
    }
  }
}

De agent kan nu vragen stellen aan je interne kennisbank. Dit is waardevol voor grote organisaties met veel domeinkennis die niet in de codebase zelf staat.

Use case 6: spec-driven development

In complexe projecten laat je OpenCode niet zomaar code schrijven, maar werk je vanuit een specificatie. Het patroon:

1. Schrijf of genereer een spec in .opencode/specs/ of ~/openspec/changes/.
2. Start de agent in plan mode.
3. De agent leest de spec, stelt een implementatieplan voor en wacht op goedkeuring.
4. Na approval voert de agent het plan uit in scoped stappen.
5. Elke wijziging wordt gecommit met verwijzing naar de spec.

opencode -p "Implement the auth refactor described in .opencode/specs/auth-refactor.md"

Dit patroon combineert OpenCode met OpenSpec: de spec is het contract, de agent is de uitvoerder, en de approval-gate zorgt dat menselijke controle behouden blijft.

Use case 7: compliance-assisted review

Voor overheids- of financiële projecten kun je een compliance-agent configureren die specifiek checkt tegen BIO2, EU AI Act of NIS2:

---
model: anthropic/claude-sonnet-4-6
mode: subagent
description: BIO2 compliance reviewer
permission:
  read: allow
  grep: allow
  bash: deny
  edit: deny
---

You are a BIO2 compliance reviewer. Check code and config for:
- logging of security-relevant events
- least-privilege access controls
- auditability of mutations
- data residency and encryption
- supplier risk and exit strategy
Reference ~/openspec/specs/bio2-baseline.md for the current baseline.
Report findings with severity and remediation.

Start de agent met:

opencode run --agent bio2-reviewer -f src/ "Review this directory against BIO2"

Dit maakt compliance geen eenmalige audit, maar een herhaalbaar onderdeel van de ontwikkelworkflow.

12. Observability en FinOps

Zonder inzicht in gebruik loop je al snel tegen hoge kosten of onverklaarbare pieken aan. OpenCode biedt enkele ingebouwde mechanismen:

Token tracking

Plugins zoals opencode-token-tracker tonen na elk antwoord:

• input/output tokens
• cache hits
• reasoning tokens
• latentie
• kosten per bericht
• cumulatieve sessiekosten

Stats

opencode stats --days 7 --models --tools

Geeft een overzicht van gebruik per model, tool en project.

Metrics die je wilt bijhouden

Een volwassen OpenCode-setup meet minimaal:

Metric	Waarom
Prompts per taak	Geeft aan hoeveel interactie een agent nodig heeft
Tokens per prompt/response	Directe kostenbepaler
Tool calls per taak	Toont of de agent efficiënt zoekt en wijzigt
Latency per model	Helpt bij modelkeuze voor tijdkritische taken
Cache hit rate	Reasoning-modellen zijn duurder zonder caching
Cumulatieve sessiekosten	Voorkomt budgetovertredingen
Test pass rate na agent-wijzigingen	Meet kwaliteit, niet alleen snelheid
Review tijd per agent-PR	Socio-technische kosten

Deze metrics kun je verzamelen via plugins, opencode stats of door logs naar een centrale observability-stack te sturen. Zonder meten versnel je alleen maar je ongecontroleerde uitgaven.

Budgetcaps

Op provider-niveau kun je allowlists en limieten configureren. In combinatie met een interne gateway kun je per team of project budgetcaps afdwingen. Zelf biedt OpenCode nog geen ingebouwde budgetlimit; daarvoor zijn plugins of gateway-configuratie nodig.

Logging

OpenCode schrijft logs naar ~/.local/share/opencode/logs/. Je kunt het logniveau instellen via logLevel of --log-level. Voor productie is het raadzaam om logs naar een centrale SIEM te sturen, bijvoorbeeld met een plugin die client.app.log() gebruikt.

13. Troubleshooting en debugging

Wanneer iets niet werkt, zijn dit de eerste stappen:

1. Controleer de logs:

   opencode --print-logs
   

2. Start zonder plugins om conflicten uit te sluiten:

   opencode --pure
   

3. Debug een MCP-server:

   opencode mcp debug <name>
   

4. Controleer of het model beschikbaar is:

   opencode models <provider> --verbose
   

5. Bekijk de huidige config:

   opencode debug config
   

   Let op: dit toont mogelijk gevoelige waarden. Gebruik het alleen lokaal en deel de output niet.

6. Test een plugin in isolatie:

   opencode --pure --plugin ./.opencode/plugins/suspect.ts
   

7. Controleer permissies:

   opencode run "What permissions do I have?"
   

Voor netwerkproblemen met remote MCP of providers is het nuttig om met curl de endpoints direct te testen buiten OpenCode om.

14. Veelgemaakte fouten en anti-patronen

OpenCode geeft veel vrijheid, maar die vrijheid leidt snel naar valkuilen. Deze zien we regelmatig:

Te veel plugins tegelijk

Elke plugin voegt tools, hooks en context toe. Begin met één plugin, test, voeg pas een tweede toe als de eerste stabiel is. Vijf plugins op dag één leidt tot onvoorspelbaar gedrag en hoge tokenkosten.

Geen permissions ingeregeld

Standaard rechten geven agents veel ruimte. Pas permission expliciet aan voordat je aan een gevoelige codebase werkt. Vooral bash: allow zonder restricties is vragen om problemen.

.env inlezen door agents

Agents lezen graag .env files om configuratie te begrijpen. Configureer envsitter-guard of een vergelijkbare plugin om dit te blokkeren. Lees nooit secrets in modelcontext.

Modelkeuze negeren

Niet elke taak vereist een frontier model. Gebruik small_model voor eenvoudige taken, configureer goedkopere modellen voor summaries en reserveer dure reasoning-modellen voor complexe refactors.

Geen logging of audit trail

OpenCode logt lokaal, maar zonder centrale opslag verlies je het overzicht. Zorg dat logs, sessie-exports en tool-call-historie worden bewaard, vooral in gereguleerde omgevingen.

Alles in één sessie proberen te doen

Contextwindows zijn beperkt. Gebruik plan mode, subagents en handoff-mechanismen om langlopende taken op te splitsen. Dit verhoogt kwaliteit en verlaagt kosten.

Vergeten dat OpenCode geen enterprise control plane is

OpenCode is de engine, niet het complete voertuig. Je moet zelf zorgen voor SSO, centrale policy, sandboxing, egress-controle, secret management en FinOps. Verwacht niet dat een open-source CLI dit out-of-the-box levert.

15. Conclusie

OpenCode is geen kant-en-klare AI-assistent; het is een open platform dat je zelf vormgeeft. Dat vraagt meer werk dan Claude Code of Copilot, maar levert ook iets op dat proprietaire tools niet kunnen bieden: volledige controle over model, data, tools, agents en governance.

Dit artikel liet zien hoe je OpenCode configureert als een modulair AI-engineering-platform. We behandelden provider-routing, eigen agents, MCP-servers, plugins, skills, permissions, headless execution, observability, troubleshooting, veelgemaakte fouten en concrete use cases. We legden ook de koppeling met OpenSpec en het Open Knowledge Framework, omdat technische mogelijkheden pas waarde creëren als ze ingebed zijn in governance en kennismanagement.

De rode draad is simpel: begin klein, bouw je control plane expres uit en breid alleen uit wat je echt nodig hebt. OpenCode schaalt mee van persoonlijke assistant tot enterprise agent platform, maar alleen als je de architectuur bewust ontwerpt.

Voor organisaties die strikte eisen hebben aan data-soevereiniteit, auditability en vendor-lock-in, zoals de Nederlandse publieke sector, is OpenCode een strategisch alternatief. Voor snelle productteams kan het samenwerken met proprietaire tools, waarbij OpenCode de soevereine of geavanceerde use cases afdekt. En voor AI-engineers die hun toolchain willen begrijpen en beheersen, is OpenCode een van de weinige platforms waar je daadwerkelijk alles kunt inspecteren en aanpassen.

Snelle start-checklist

1. Installeer OpenCode en log in bij je provider(s).
2. Maak een globale opencode.json met veilige defaults.
3. Voeg per project een AGENTS.md toe.
4. Configureer permission met edit: ask en een beperkte bash-allowlist.
5. Start met één plugin, bijvoorbeeld opencode-token-tracker.
6. Voeg een MCP-server toe die je werk echt versnelt, zoals Playwright of Context7.
7. Experimenteer met een eigen agent voor een herhaalde taak.
8. Breid uit naar spec-driven development en compliance-review agents.

Wil je weten hoe OpenCode past binnen jouw organisatie, je bestaande SDLC of een soevereine AI-architectuur? Neem contact op met DjimIT voor een verkenning.

Bronnen

• OpenCode
• OpenCode Docs
• OpenCode Enterprise
• awesome-opencode
• Model Context Protocol
• Eerdere DjimIT-artikelen: OpenCode is de Linux van agents en OpenCode vs Claude Code in productiecodebases