文档导航： 入门指南 主题配置 快捷键 代码格式化 配置说明

配置说明

使用 OpenCode JSON 配置。

您可以使用 JSON 配置文件来配置 OpenCode。

格式

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）格式。

{
  "$schema": "https://opencode.ai/config.json",
  // 主题配置
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
}

位置

您可以将配置放在几个不同的位置，它们有不同的优先级顺序。

全局配置

将您的全局 OpenCode 配置放在 ~/.config/opencode/opencode.json。您将希望使用全局配置来配置主题、提供商或快捷键等内容。

项目配置

您还可以在项目中添加 opencode.json。它的优先级高于全局配置。这对于配置特定于您的项目的提供商或模式很有用。

当 OpenCode 启动时，它会在当前目录中查找配置文件，或者向上遍历到最近的 Git 目录。

这也可以安全地检入 Git，并且使用与全局配置相同的模式。

自定义路径

您还可以使用 OPENCODE_CONFIG 环境变量指定自定义配置文件路径。这优先于全局和项目配置。

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

自定义目录

您可以使用 OPENCODE_CONFIG_DIR 环境变量指定自定义配置目录。该目录将被搜索代理、命令、模式和插件，就像标准的 .opencode 目录一样，并且应该遵循相同的结构。

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"
注意： 自定义目录在全局配置和 .opencode 目录之后加载，因此它可以覆盖它们的设置。

模式

配置文件具有在 opencode.ai/config.json 中定义的模式。

您的编辑器应该能够基于模式进行验证和自动完成。

TUI 配置

您可以通过 tui 选项配置 TUI 特定的设置。

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

可用选项：

在此处了解有关使用 TUI 的更多信息。

工具

您可以通过 tools 选项管理 LLM 可以使用的工具。

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

模型

您可以通过 provider、model 和 small_model 选项在 OpenCode 配置中配置您要使用的提供商和模型。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

small_model 选项为轻量级任务（如标题生成）配置单独的模型。默认情况下，OpenCode 尝试使用提供商提供的更便宜的模型（如果有），否则回退到您的主模型。

您还可以配置本地模型。了解更多。

主题

您可以通过 theme 选项在 OpenCode 配置中配置您要使用的主题。

{
  "$schema": "https://opencode.ai/config.json",
  "theme": ""
}

代理（Agents）

您可以通过 agent 选项为特定任务配置专门的代理。

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // 为仅审查代理禁用文件修改工具
        "write": false,
        "edit": false,
      },
    },
  },
}

您还可以在 ~/.config/opencode/agent/ 或 .opencode/agent/ 中使用 markdown 文件定义代理。在此处了解更多。

分享

您可以通过 share 选项配置分享功能。

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

此选项接受：

默认情况下，分享设置为手动模式，您需要使用 /share 命令显式分享对话。

命令

您可以通过 command 选项为重复性任务配置自定义命令。

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component",
    },
  },
}

您还可以在 ~/.config/opencode/command/ 或 .opencode/command/ 中使用 markdown 文件定义命令。在此处了解更多。

快捷键

您可以通过 keybinds 选项自定义您的快捷键。

{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {}
}

自动更新

OpenCode 将在启动时自动下载任何新更新。您可以使用 autoupdate 选项禁用此功能。

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

格式化工具

您可以通过 formatter 选项配置代码格式化工具。

{
  "$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"]
    }
  }
}

在此处了解有关格式化工具的更多信息。

权限

默认情况下，opencode 允许所有操作 而不需要显式批准。您可以使用 permission 选项更改此设置。

例如，要确保 edit 和 bash 工具需要用户批准：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

在此处了解有关权限的更多信息。

MCP 服务器

您可以通过 mcp 选项配置您要使用的 MCP 服务器。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

指令

您可以通过 instructions 选项配置您正在使用的模型的指令。

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

这接受指令文件路径和 glob 模式的数组。在此处了解有关规则的更多信息。

禁用的提供商

您可以使用 disabled_providers 选项禁用自动加载的提供商。当您想要阻止某些提供商加载（即使其凭据可用）时，这很有用。

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

disabled_providers 选项接受提供商 ID 数组。当提供商被禁用时：

变量

您可以在配置文件中使用变量替换来引用环境变量和文件内容。

环境变量

使用 {env:VARIABLE_NAME} 来替换环境变量：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

如果未设置环境变量，它将被替换为空字符串。

文件

使用 {file:path/to/file} 来替换文件内容：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

文件路径可以是：

这些对于以下内容很有用：

文档导航： 入门指南 主题配置 快捷键 代码格式化 配置说明