Six reference pages, each a single-purpose cheatsheet: - cli.md: full CLI surface (21 commands + global flags + experimental env vars) sourced from packages/web/src/content/docs/cli.mdx - slash-commands.md: every built-in TUI slash command verified against packages/web/src/content/docs/tui.mdx - permissions.md: all 17 permission keys verified against PermissionConfig in the JSON schema (read, edit, bash, glob, grep, list, task, todowrite, question, external_directory, repo_clone, repo_overview, webfetch, websearch, lsp, skill, doom_loop) - faq.md: covers free-vs-paid, OpenCode vs Claude Code, offline, model picks (multi-provider, not Anthropic-only), config locations, sharing, privacy, migration, troubleshooting - changelog.md: notable releases through v1.15.4 (verified via GitHub releases API, published 2026-05-17T17:44Z) - further-reading.md: curated external resources — only links that resolve (link-checked at commit time)
8.7 KiB
FAQ & Troubleshooting
Getting started
Q: Is OpenCode free?
The software is free and open-source (MIT). You pay for whichever LLM provider you use:
- OpenCode Zen — pay-as-you-go, fractions of a cent per request. Free models available for learning.
- Direct providers — your own Anthropic/OpenAI/Google/etc. account; pricing is whatever they charge.
- Local models — free if you're running Ollama/LM Studio/llama.cpp on your own hardware.
Q: What's the difference between OpenCode and Claude Code?
Briefly: OpenCode is provider-agnostic and open source; Claude Code is Anthropic-only and proprietary.
| OpenCode | Claude Code | |
|---|---|---|
| License | MIT | Proprietary |
| Models | Any provider | Anthropic only |
| Pricing | Pay-as-you-go or BYOK | Subscription |
| Config | opencode.json + .opencode/ |
.claude/settings.json + .claude/ |
| Hooks | JS/TS plugins | Python scripts |
OpenCode reads CLAUDE.md and .claude/skills/ as fallbacks for easier migration.
Q: Does OpenCode work offline?
Yes, if you point it at a local model (Ollama, LM Studio, llama.cpp). Internet access is needed for hosted providers, remote MCP servers, sharing, and updates.
Q: Which model should I use?
Honest answer: try a few on your actual workload. Benchmarks generalize poorly to specific codebases. Below are starting suggestions, not a ranking — different teams report different winners.
| Task | Reasonable options |
|---|---|
| Day-to-day coding | Claude Sonnet (4.5 direct or 4.6 via Zen), GPT-5.4, Gemini 3.1 Pro |
| Complex multi-file refactors | Claude Opus 4.7, GPT-5.5, GPT-5.5 Pro |
| Fast, lightweight tasks | Claude Haiku 4.5, GPT-5.4 Mini, GPT-5.4 Nano, GLM/Kimi |
| Long-context (>200K tokens) | GPT-5.5 (272K), Claude Sonnet 4.5/4 (>200K tier) |
| Budget-friendly | Qwen3.6 Plus, GPT-5.4 Nano, Qwen3.5 Plus, MiniMax M2.7 |
| Local / offline | Ollama or LM Studio with a coding-tuned model that fits your hardware (Qwen 2.5 Coder, DeepSeek Coder, CodeLlama — quality varies hugely with model size and quantization) |
Use a cheaper model for explore/scout subagents — they read a lot but don't need to write. See ../zen.md for full pricing and the cheap-explorer / strong-executor pattern.
No single model wins every benchmark, and benchmarks don't predict your code. If a model feels wrong, switch — model identity matters more than people often think.
Configuration
Q: Where does OpenCode store config?
| Type | Path |
|---|---|
| User config | ~/.config/opencode/opencode.json |
| Project config | opencode.json in project root |
| Project assets | .opencode/ in project root |
| Sessions / cache | ~/.local/share/opencode/ (Linux/macOS) |
| Logs | ~/.local/share/opencode/log/ |
| Custom path | Set OPENCODE_CONFIG=<path> |
Configs merge from low to high priority: remote .well-known/opencode → global → custom path → project → .opencode/ → inline env var → managed → macOS MDM.
Q: How do I share config across a team?
Commit opencode.json, AGENTS.md, .opencode/agents/, .opencode/commands/, .opencode/skills/, and .opencode/plugins/ to your repo. Every contributor's OpenCode picks them up.
For org-wide defaults, use managed configs (/Library/Application Support/opencode/ on macOS, /etc/opencode/ on Linux, %ProgramData%\opencode on Windows) — they override user config but lose to MDM-pushed configs.
Q: How do I use a remote config endpoint?
Configure your domain's .well-known/opencode to return JSON. OpenCode fetches it as the lowest-priority config layer — useful for org-wide defaults that users can override.
Commands & skills
Q: Custom command vs. skill vs. agent — which should I write?
| You want… | Reach for… |
|---|---|
A /<name> the user types |
Custom command in .opencode/commands/ |
| Workflow the agent discovers when the description matches | Skill in .opencode/skills/<name>/SKILL.md |
| A persistent role with its own model and permissions | Agent in .opencode/agents/<name>.md |
See ../commands.md, ../skills.md, ../agents.md.
Q: My skill isn't being discovered. Why?
Almost always the description is too vague. Skills load when the model decides the description matches the task. Rewrite the description to:
- Start with what it does (verb-first)
- Name the output concretely
- Include a trigger phrase ("Use when…")
Bad: Helps with releases
Good: Draft release notes from merged PRs, propose a semver bump, emit a gh release create command. Use when preparing a tagged release.
Q: Why is my agent slow?
Most common culprits:
- Too many MCP tools loaded → run
opencode mcp list, disable noisy ones intools. - Big context →
/compactaggressively. - Slow model → switch to a faster one with
/models. - Watcher choking on large repo → add ignore patterns under
watcher.ignoreinopencode.json.
CLI & headless
Q: How do I run OpenCode in CI?
curl -fsSL https://opencode.ai/install | bash
opencode run --agent plan --format json "audit src/ for security issues" > findings.json
For unattended runs, --dangerously-skip-permissions auto-approves anything that isn't explicitly denied — only after auditing what your prompt and tools can do.
Q: Can I attach a remote OpenCode server?
Yes:
# Server side
opencode serve --port 4096 --hostname 0.0.0.0
# Client side
opencode attach http://server.local:4096
The TUI talks to the remote server. Add --username / --password for basic auth.
Q: How do I track token cost?
opencode stats --days 30 --models # by model
opencode stats --days 30 --tools # by tool
opencode stats --days 30 --project myrepo
Migration
Q: I'm coming from Claude Code. What changes?
See ../migration.md for the full guide. Quick version:
- Rename
CLAUDE.md→AGENTS.md - Move
.claude/commands/→.opencode/commands/ - Move
.claude/skills/→.opencode/skills/ - Rewrite Python hooks as JS/TS plugins in
.opencode/plugins/ - Update agent frontmatter — different field names
Q: Do my Cursor rules work?
Yes — reference them from opencode.json:
{
"instructions": [".cursor/rules/*.md", "AGENTS.md"]
}
Privacy & data
Q: Where does my code go?
- Local models — nowhere. Code stays on your machine.
- Direct providers — the prompt and edited files go to whichever provider you authenticated with, subject to their policy.
- Zen — Zen is a gateway; the underlying provider's policy still applies, plus Zen's policy for billing/routing. Check opencode.ai/docs/zen for the current statement.
- Sharing (
/share) — opt-in. Shared conversations live on OpenCode's servers until you unshare them.
Q: How do I disable sharing entirely?
{ "share": "disabled" }
Commit this to opencode.json to enforce it across the team. Enterprise builds can also push this via managed config.
Q: How do I protect secrets?
Three layers:
permission.external_directory: "deny"so OpenCode can't read outside the project.- A plugin that blocks
edit/writeto.env*/secrets/paths (see../plugins.md). - Don't commit secrets in the first place.
gitleaksor similar in CI.
Troubleshooting
Q: opencode: command not found after install
Add the install path to your shell:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Q: Authentication fails
opencode auth logout
opencode auth login # re-authenticate
If using Zen, regenerate the API key on the dashboard.
Q: MCP server won't connect
opencode mcp debug <server-name>
opencode --log-level DEBUG --print-logs
For OAuth servers, clear creds and re-auth:
opencode mcp logout <server-name>
opencode mcp auth <server-name>
Q: Editor (/editor) opens the wrong program
OpenCode uses $EDITOR. Set it in your shell:
export EDITOR='code --wait' # VS Code
export EDITOR='nvim' # Neovim
Q: TUI looks broken / colors wrong
- Make sure your terminal supports truecolor. Test:
echo $COLORTERMshould showtruecoloror24bit. - Try a built-in theme:
/themes→ picktokyonightorgruvbox. - Update OpenCode:
opencode upgrade.
Q: How do I report a bug?
github.com/anomalyco/opencode/issues. Include opencode --version, your OS, and a minimal reproduction.
Last reviewed: 2026-05-18 · Canonical source: opencode.ai/docs.