diff options
| -rw-r--r-- | packages/web/src/content/docs/docs/config.mdx | 150 |
1 files changed, 79 insertions, 71 deletions
diff --git a/packages/web/src/content/docs/docs/config.mdx b/packages/web/src/content/docs/docs/config.mdx index ec885d2ba..0bacf2bff 100644 --- a/packages/web/src/content/docs/docs/config.mdx +++ b/packages/web/src/content/docs/docs/config.mdx @@ -5,9 +5,11 @@ description: Using the opencode JSON config. You can configure opencode using a JSON config file. +--- + ## Format -opencode supports both JSON and JSONC (JSON with Comments) formats. You can use comments in your configuration files: +opencode supports both **JSON** and **JSONC** (JSON with Comments) formats. ```jsonc title="opencode.jsonc" { @@ -19,7 +21,14 @@ opencode supports both JSON and JSONC (JSON with Comments) formats. You can use } ``` -This can be used to configure opencode globally or for a specific project. +With JSONC, you can use comments in your configuration files: + +--- + +## Locations + +You can place your config in a couple of different locations and they have a +different order of precedence. --- @@ -31,7 +40,11 @@ Place your global opencode config in `~/.config/opencode/opencode.json`. You'll ### Per project -You can also add a `opencode.json` in your project. This is useful for configuring providers or modes specific to your project. +You can also add a `opencode.json` in your project. It takes precedence over the global config. This is useful for configuring providers or modes specific to your project. + +:::tip +Place project specific config in the root of your project. +::: When opencode starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory. @@ -39,9 +52,9 @@ This is also safe to be checked into Git and uses the same schema as the global --- -### Custom config file +### Custom path -You can specify a custom config file using the `OPENCODE_CONFIG` environment variable. This takes precedence over the global and project configs. +You can also specify a custom config file path using the `OPENCODE_CONFIG` environment variable. This takes precedence over the global and project configs. ```bash export OPENCODE_CONFIG=/path/to/my/custom-config.json @@ -111,12 +124,29 @@ You can configure the theme you want to use in your opencode config through the --- -### Logging +### Agents + +You can configure specialized agents for specific tasks through the `agent` option. -Logs are written to: +```jsonc title="opencode.jsonc" +{ + "$schema": "https://opencode.ai/config.json", + "agent": { + "code-reviewer": { + "description": "Reviews code for best practices and potential issues", + "model": "anthropic/claude-sonnet-4-20250514", + "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.", + "tools": { + // Disable file modification tools for review-only agent + "write": false, + "edit": false, + }, + }, + }, +} +``` -- **macOS/Linux**: `~/.local/share/opencode/log/` -- **Windows**: `%APPDATA%\opencode\log\` +You can also define agents using markdown files in `~/.config/opencode/agent/` or `.opencode/agent/`. [Learn more here](/docs/agents). --- @@ -169,118 +199,96 @@ opencode will automatically download any new updates when it starts up. You can --- -### MCP servers +### Formatters -You can configure MCP servers you want to use through the `mcp` option. +You can configure code formatters through the `formatter` option. ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", - "mcp": {} + "formatter": { + "prettier": { + "disabled": true + }, + "custom-prettier": { + "command": ["npx", "prettier", "--write", "$FILE"], + "environment": { + "NODE_ENV": "development" + }, + "extensions": [".js", ".ts", ".jsx", ".tsx"] + } + } } ``` -[Learn more here](/docs/mcp-servers). +[Learn more about formatters here](/docs/formatters). --- -### Instructions +### Permissions -You can configure the instructions for the model you're using through the `instructions` option. +You can configure permissions to control what AI agents can do in your codebase through the `permission` option. ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", - "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"] + "permission": { + "edit": "ask", + "bash": "ask" + } } ``` -This takes an array of paths and glob patterns to instruction files. [Learn more -about rules here](/docs/rules). +[Learn more about permissions here](/docs/permissions). --- -### Agents +### MCP servers -You can configure specialized agents for specific tasks through the `agent` option. +You can configure MCP servers you want to use through the `mcp` option. -```jsonc title="opencode.jsonc" +```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", - "agent": { - "code-reviewer": { - "description": "Reviews code for best practices and potential issues", - "model": "anthropic/claude-sonnet-4-20250514", - "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.", - "tools": { - // Disable file modification tools for review-only agent - "write": false, - "edit": false, - }, - }, - }, + "mcp": {} } ``` -You can also define agents using markdown files in `~/.config/opencode/agent/` or `.opencode/agent/`. [Learn more here](/docs/agents). +[Learn more here](/docs/mcp-servers). --- -### Disabled providers - -You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available. - -The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled: - -- It won't be loaded even if environment variables are set -- It won't be loaded even if API keys are configured through `opencode auth login` -- The provider's models won't appear in the model selection list +### Instructions +You can configure the instructions for the model you're using through the `instructions` option. ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", - "disabled_providers": ["openai", "gemini"] + "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"] } ``` ---- +This takes an array of paths and glob patterns to instruction files. [Learn more +about rules here](/docs/rules). -### Formatters +--- -You can configure code formatters through the `formatter` option. See [Formatters documentation](/docs/formatters) for more details. +### Disabled providers -```json title="opencode.json" -{ - "$schema": "https://opencode.ai/config.json", - "formatter": { - "prettier": { - "disabled": true - }, - "custom-prettier": { - "command": ["npx", "prettier", "--write", "$FILE"], - "environment": { - "NODE_ENV": "development" - }, - "extensions": [".js", ".ts", ".jsx", ".tsx"] - } - } -} -``` +You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available. ---- +The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled: -### Permissions +- It won't be loaded even if environment variables are set +- It won't be loaded even if API keys are configured through `opencode auth login` +- The provider's models won't appear in the model selection list -You can configure permissions to control what AI agents can do in your codebase through the `permission` option. ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", - "permission": { - "edit": "ask", - "bash": "ask" - } + "disabled_providers": ["openai", "gemini"] } ``` |