# OpenCode Configuration Options and Precedence Order: The Complete Guide

> Master OpenCode configuration options and precedence. Understand how seven sources merge, from managed directories to remote endpoints, ensuring optimal control for your projects.

- Repository: [Anomaly/opencode](https://github.com/anomalyco/opencode)
- Tags: how-to-guide
- Published: 2026-02-16

---

**OpenCode merges configuration from seven distinct sources, with later sources overriding earlier ones: managed config directories (highest precedence), inline environment variables, `.opencode` directories, project config files, custom config paths, global user config, and remote well-known endpoints (lowest precedence).**

OpenCode, the open-source AI coding assistant from `anomalyco/opencode`, uses a hierarchical configuration system to determine runtime behavior. Understanding OpenCode's configuration options and precedence order is essential for customizing the editor, managing enterprise deployments, and debugging environment-specific issues.

## Configuration Precedence Order in OpenCode

The loading pipeline in [`packages/opencode/src/config/config.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/config/config.ts) processes seven configuration sources sequentially, with each subsequent source merging into—and overriding—the previous accumulator. The comment at lines 71-78 documents this hierarchy explicitly.

### The Seven Configuration Sources (Lowest to Highest Precedence)

1. **Remote well-known config** (`/.well-known/opencode`): Organization-wide defaults fetched from a remote server when an authentication token is present.
2. **Global user config** (`~/.config/opencode/*`): Local global configuration files and remote org defaults merged together.
3. **Custom config path** (`OPENCODE_CONFIG`): A specific file path provided via CLI flag or environment variable.
4. **Project config** ([`opencode.json`](https://github.com/anomalyco/opencode/blob/main/opencode.json) or `opencode.jsonc`): Discovered by walking up the directory tree from the current working directory, with closer files taking precedence.
5. **`.opencode` directories**: Scanned in both the user's home directory (`~/.opencode`) and project trees, containing subdirectories for `agents/`, `commands/`, `plugins/`, and additional JSONC files.
6. **Inline config** (`OPENCODE_CONFIG_CONTENT`): Raw JSON supplied directly via environment variable, parsed and merged immediately before managed config.
7. **Managed config directory** (`managedConfigDir`): Enterprise-only path (typically `/etc/opencode` on Linux) containing admin-controlled settings that override every other source.

### Merge Behavior

The `merge` helper function defined at lines 56-66 in [`packages/opencode/src/config/config.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/config/config.ts) handles the combination of configuration objects. For scalar values, later sources overwrite earlier ones. For array fields—such as `plugin` and `instructions`—the function concatenates arrays rather than replacing them, ensuring cumulative configuration from multiple layers.

## OpenCode Configuration Options (The Info Schema)

All configuration options are defined and validated by the `Info` Zod schema in [`packages/opencode/src/config/config.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/config/config.ts). The schema supports dozens of optional fields organized into functional categories.

### Core Application Settings

- **`$schema`**: JSON Schema URI for validation.
- **`theme`**: UI theme name for the terminal interface.
- **`logLevel`**: Verbosity control (`error`, `warn`, `info`, `debug`).
- **`username`**: Custom display name overriding the system username.
- **`autoupdate`**: Update behavior (`true`, `false`, `"notify"`).

### Model and Provider Configuration

- **`model`** / **`small_model`**: Default model identifiers in `provider/model` format.
- **`default_agent`**: Primary agent name when none is specified.
- **`disabled_providers`** / **`enabled_providers`**: Provider whitelist/blacklist.
- **`provider`**: Per-provider configuration object containing API keys, timeouts, and model overrides.

### Interface and Server Options

- **`keybinds`**: Custom keyboard shortcuts mapping.
- **`tui`**: Terminal UI settings including scroll speed and diff style.
- **`server`**: HTTP server configuration (`port`, `hostname`, `mdns`, `cors`).

### Extensions and Integrations

- **`plugin`**: Array of plugin specifiers (npm packages or `file://` URLs).
- **`skills`**: Paths or URLs to additional skill directories.
- **`mcp`**: Model Context Protocol server configurations.
- **`lsp`**: Language Server Protocol integration settings.
- **`formatter`**: Code formatting options.

### Advanced and Experimental

- **`instructions`**: Array of glob patterns or file paths containing extra system prompts.
- **`experimental`**: Feature flags for unstable capabilities (`disable_paste_summary`, `batch_tool`, `openTelemetry`).
- **`compaction`**: Context compaction settings (`auto`, `prune`, `reserved`).
- **`permission`**: Fine-grained tool permission matrix.
- **`snapshot`**: Boolean controlling filesystem snapshots before command execution.

## Practical Configuration Examples

### Loading Configuration at Runtime

```typescript
import { Config } from "@opencode-ai/opencode";

async function showConfig() {
  const { config } = await Config.state(); // triggers the loading pipeline
  console.log("Effective OpenCode config:", config);
}
showConfig();

```

### Overriding Settings via Environment Variables

```typescript
// Highest precedence inline config
process.env.OPENCODE_CONFIG_CONTENT = JSON.stringify({
  theme: "solarized-dark",
  server: { port: 8080 },
});

await Config.state(); // config now contains the overridden values

```

### Using a Custom Configuration File

```typescript
// CLI flag: --config /path/to/custom.opencode.jsonc
import { Flag } from "@opencode-ai/flag";

Flag.OPENCODE_CONFIG = "/path/to/custom.opencode.jsonc";
await Config.state(); // merges after global config but before project config

```

## Key Source Files

| **File** | **Purpose** | **Link** |
|---|---|---|
| [`packages/opencode/src/config/config.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/config/config.ts) | Core configuration loading, merging logic, and `Info` schema definition. | [View source](https://github.com/anomalyco/opencode/blob/dev/packages/opencode/src/config/config.ts) |
| [`packages/opencode/src/config/markdown.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/config/markdown.ts) | Parses `.md` command and agent files consumed by the config loader. | [View source](https://github.com/anomalyco/opencode/blob/dev/packages/opencode/src/config/markdown.ts) |
| [`packages/opencode/src/util/filesystem.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/util/filesystem.ts) | Helper utilities for locating config files by walking the directory tree. | [View source](https://github.com/anomalyco/opencode/blob/dev/packages/opencode/src/util/filesystem.ts) |
| [`packages/opencode/src/flag/flag.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/flag/flag.ts) | CLI flag definitions including `OPENCODE_CONFIG` and `OPENCODE_CONFIG_CONTENT`. | [View source](https://github.com/anomalyco/opencode/blob/dev/packages/opencode/src/flag/flag.ts) |
| [`packages/opencode/src/auth/index.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/auth/index.ts) | Authentication token retrieval for remote well-known config fetching. | [View source](https://github.com/anomalyco/opencode/blob/dev/packages/opencode/src/auth/index.ts) |

## Summary

- OpenCode loads configuration from **seven distinct sources**, with later sources overriding earlier ones according to the precedence hierarchy documented in [`packages/opencode/src/config/config.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/config/config.ts).
- **Managed config directories** hold the highest precedence (enterprise deployments), while **remote well-known endpoints** provide the lowest precedence (organization defaults).
- The `merge` helper concatenates arrays (for `plugin` and `instructions`) while overwriting scalars, ensuring cumulative configuration from multiple layers.
- All options are validated against the `Info` Zod schema, covering models, providers, UI settings, MCP servers, LSP integration, and experimental features.

## Frequently Asked Questions

### What is the highest priority configuration source in OpenCode?

The **managed config directory** (`managedConfigDir`, typically `/etc/opencode` on Linux) holds the highest precedence. This enterprise-only source is loaded last in the pipeline and overrides all other configuration layers, allowing administrators to enforce organization-wide policies that users cannot override.

### How does OpenCode handle conflicting array values like plugins?

OpenCode uses a custom `merge` function defined at lines 56-66 in [`packages/opencode/src/config/config.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/config/config.ts) that **concatenates arrays** rather than replacing them. This means if you define `plugin` entries in both your global user config and project config, all plugins from both sources are loaded, with later entries appended to the array.

### Can I override OpenCode settings without creating a file?

Yes. You can use the **`OPENCODE_CONFIG_CONTENT`** environment variable to supply raw JSON configuration directly. This inline config has the second-highest precedence (after managed directories) and overrides any file-based settings. Alternatively, use the `--config` CLI flag to specify a custom file path.

### Where does OpenCode look for project configuration files?

OpenCode searches for [`opencode.json`](https://github.com/anomalyco/opencode/blob/main/opencode.json) or `opencode.jsonc` files by **walking up the directory tree** from the current working directory. It merges all discovered files, with configurations closer to the project root taking precedence over those found higher in the filesystem hierarchy. This logic is implemented in [`packages/opencode/src/util/filesystem.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/util/filesystem.ts).