opencode.jsonc Config Guide: 7 Checks Before You Commit

The useful answer is not just where the file goes. Use opencode.jsonc for reviewable, non-secret OpenCode settings, keep credentials outside the repo, understand how global and project config merge, then validate providers, models, permissions, and rollback before the file becomes team policy.

OpenCode's official config docs describe JSON and JSONC support, so comments are useful for explaining why a project setting exists. Treat those comments as operational notes: who owns the choice, when it was verified, and what command proves it still works.

Good config files avoid secrets. Put model choices, shell preferences, tool posture, permission defaults, and project-owned paths in config. Keep API keys, provider tokens, private base URLs, proxy passwords, and deployment credentials in environment variables or the provider's credential flow.

The official config page lists several locations and explains that configuration files are merged rather than fully replaced. That matters because a global preference can combine with a project model or permission rule unless a later layer overrides the same key.

For solo work, global config is convenient for personal provider and editor habits. For a team, project config is better for rules everyone should review: default model family, ignored paths, command posture, MCP decisions, and permission expectations. Managed config belongs to organizations that need non-overridable defaults.

Provider and model entries should be copied from current official docs or provider dashboards, not guessed from marketing names. A config that uses the wrong model ID can look valid as JSON while failing only when OpenCode starts a real request.

Use one primary model and one small or cheaper model only when the workflow benefits from that split. Record why the model was chosen: latency, cost, context window, local availability, or compliance. If the reason changes, the config should be reviewed instead of silently inherited.

Permissions are the part of opencode.jsonc most likely to affect safety. Start with ask for edits and shell commands until the repository proves which actions are repetitive, reversible, and low risk. Exact test or formatting commands can become narrow allows after the first clean diff.

Do not let one annoying prompt justify a broad allow rule. Package installs, deletes, migrations, deploys, pushes, secret files, and external directories should remain denied or explicitly reviewed. If an agent or MCP tool needs an exception, keep that exception close to the role or integration that requires it.

Add the official schema URL so editors can validate and autocomplete. Schema validation is not a full safety check, but it catches misspelled keys, wrong value shapes, and outdated assumptions before you debug behavior inside a live session.

Pair schema validation with a short human review. Check whether every key is non-secret, whether comments are accurate, whether project rules belong in the repo, and whether any value is version-sensitive. Config should be readable by the next maintainer, not only accepted by the editor.

Before committing a new opencode.jsonc, test it in a disposable or low-risk repository. Run a config debug command when available, start OpenCode, list models, read a file, attempt a small edit, run the expected test command, and confirm a denied action really stops.

The validation result should be written down near the config or in the pull request. Include operating system, shell, provider, model ID, command tested, and rollback step. That note turns the file from a guess into a reproducible baseline.

1. Create a minimal fileStart with schema, model choice, and one reviewed permission posture.
2. Validate syntaxUse editor schema support or JSONC-aware tooling before running OpenCode.
3. Resolve layersCheck whether global, project, custom path, or managed config wins.
4. Run a small taskRead a file, make a harmless edit, and execute a known command.
5. Test denialTry one intentionally blocked action and confirm it does not run.
6. Record rollbackDocument how to remove the rule or start without the custom file.

When config breaks, isolate the layer before rewriting everything. Check JSONC syntax, current working directory, Git root discovery, global overrides, project overrides, environment variables, provider availability, and permission prompts in that order.

For Windows questions such as opening the config file or choosing PowerShell, separate file location from shell behavior. A valid project config can still fail if the integrated terminal cannot see the provider environment variables or if the shell value points to a command that does not exist on that machine.