配置

OpenCode 使用 JSON 配置文件进行自定义。本页面介绍配置格式、文件位置和关键选项。

格式

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）两种格式：

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096
  }
}

$schema 字段启用 IDE 自动补全和验证。

配置文件位置

配置文件按以下顺序加载，后来者覆盖前者：

优先级	位置	用途
1（最低）	远程（.well-known/opencode）	组织默认配置
2	全局（~/.config/opencode/opencode.json）	用户偏好
3	自定义（OPENCODE_CONFIG 环境变量）	自定义覆盖
4（最高）	项目（项目根目录的 opencode.json）	项目特定设置

此外，.opencode 目录和 OPENCODE_CONFIG_CONTENT（内联配置）可以提供运行时覆盖。

TIP

配置文件是合并的，不是替换的。所有位置的非冲突设置都会被保留。冲突的键按优先级解析。

全局配置

将用户级偏好放在 ~/.config/opencode/opencode.json：

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

项目配置

在项目根目录添加 opencode.json。可以安全地提交到 Git：

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

关键选项

模型选择

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

• model — 编码任务的主要模型
• small_model — 用于标题生成等轻量任务的较便宜模型

供应商配置

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000
      }
    }
  }
}

• timeout — 请求超时时间（毫秒，默认：300000）
• chunkTimeout — 流式响应块之间的超时时间

工具

启用或禁用 LLM 可以使用的工具：

{
  "tools": {
    "write": false,
    "bash": false
  }
}

权限

控制工具行为 — 允许、拒绝或需要审批：

{
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "allow"
  }
}

支持通配符批量配置：

{
  "permission": {
    "mymcp_*": "ask"
  }
}

指令（规则）

指向引导 AI 的指令文件：

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

代理

定义用于特定任务的专业代理：

{
  "agent": {
    "code-reviewer": {
      "description": "审查代码的最佳实践和潜在问题",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一个代码审查员。关注安全性、性能和可维护性。",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

自定义命令

创建可复用的命令：

{
  "command": {
    "test": {
      "template": "运行完整的测试套件并生成覆盖率报告，显示所有失败项。",
      "description": "运行测试并生成覆盖率",
      "agent": "build"
    }
  }
}

分享

{
  "share": "manual"
}

选项："manual"（默认）、"auto" 或 "disabled"。

上下文压缩

控制对话过长时的上下文压缩行为：

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

快照

OpenCode 使用快照跟踪文件变更，支持撤销/重做。对大型仓库可禁用：

{
  "snapshot": false
}

自动更新

{
  "autoupdate": false
}

设为 "notify" 可在有新版本时收到通知但不自动下载。

MCP 服务器

{
  "mcp": {
    "my-server": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "enabled": true
    }
  }
}

插件

从 npm 或本地文件加载插件：

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

变量替换

环境变量

使用 {env:VARIABLE_NAME} 引用环境变量：

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

文件内容

使用 {file:path/to/file} 包含文件内容：

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

TUI 配置

TUI 专用设置使用单独的 tui.json 文件：

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "scroll_speed": 3,
  "diff_style": "auto"
}

放在 opencode.json 旁边（全局或项目级别）。

延伸阅读

• 官方配置文档
• 配置 JSON Schema
• TUI JSON Schema