OpenCode 配置文件

OpenCode 使用 JSON 格式来配置。

我们可以先看在全局配置文件 ~/.config/opencode/opencode.json：

touch ~/.config/opencode/opencode.json

包含模型提供商及配置信息：

{
  // JSON Schema（用于编辑器校验和自动补全）
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    // 自定义 Provider 名称（使用时：deepseek/xxx）
    "deepseek": {

      // 使用 OpenAI 兼容适配器（适用于 DeepSeek 这类兼容接口）
      "npm": "@ai-sdk/openai-compatible",

      "options": {
        // API 基础地址（必须是 OpenAI 兼容格式）
        "baseURL": "https://api.deepseek.com/v1",

        // API Key
        "apiKey": "sk-xxxx",

        // 是否强制设置缓存 key（提升缓存命中率，降低成本）
        "setCacheKey": true
      },

      "models": {
        // 本地模型别名（CLI/TUI 中使用：deepseek/Deepseek-v4）
        "Deepseek-v4": {
          // 实际调用的模型名称（API 层）
          "name": "deepseek-v4-pro"
        }
      }
    }
  }
}

一个最小可用配置示例

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

常用全局配置项：

配置项 类型 说明
model string 默认主模型
small_model string 轻量任务模型（如标题生成）
autoupdate boolean / "notify" 自动更新策略
theme string UI 主题
provider object 模型提供商配置

Provider 示例:

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

理解配置的"合并机制"

OpenCode 的配置不是覆盖，而是分层合并。

加载顺序（由低到高）

顺序 来源 说明
1 远程 .well-known/opencode 组织默认配置
2 全局配置 ~/.config/opencode/opencode.json
3 自定义路径 OPENCODE_CONFIG
4 项目配置 项目中的 opencode.json
5 .opencode/ 目录 扩展能力
6 内联配置 OPENCODE_CONFIG_CONTENT

合并规则

  • 不冲突字段：全部保留
  • 冲突字段：后者覆盖前者

示例

全局配置：

{
  "autoupdate": true
}

项目配置：

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

最终结果：

{
  "autoupdate": true,
  "model": "anthropic/claude-sonnet-4-5"
}

项目配置

在项目根目录创建：

opencode.json

作用:

  • 定义项目专属 AI 行为
  • 可提交到 Git
  • 覆盖全局配置

示例：项目级配置

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

核心配置模块详解

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

模型与 Provider

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}
字段 说明
model 主任务模型
small_model 低成本任务模型

工具控制

{
  "tools": {
    "write": false,
    "bash": false
  }
}
工具 作用
write 写文件
bash 执行命令

这是安全控制的第一层。

权限控制

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}
值 含义
allow 自动执行
ask 每次确认
deny 禁止

Agent（核心能力）

{
  "agent": {
    "code-reviewer": {
      "description": "代码审查",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer",
      "tools": {
        "write": false
      }
    }
  }
}

本质：给 AI 定义角色 + 能力范围

Command（自动化 Prompt）

{
  "command": {
    "test": {
      "template": "Run tests and fix failures",
      "description": "运行测试"
    }
  }
}

本质：Prompt 模板系统

TUI 配置

{
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Server 配置（API / Web）

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true
  }
}

上下文压缩（Token 优化）

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

插件系统

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

MCP（扩展生态）

{
  "mcp": {}
}

用于接入外部工具（如 Jira、数据库等）

指令系统（AI 规则）

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

Provider 控制

{
  "enabled_providers": ["anthropic"],
  "disabled_providers": ["openai"]
}

优先级：

disabled > enabled

变量系统

环境变量:

{
  "model": "{env:OPENCODE_MODEL}"
}

文件引用

{
  "apiKey": "{file:~/.secrets/key}"
}

目录扩展机制

OpenCode 不只是 JSON 配置，还支持目录扩展：

.opencode/
├── agents/
├── commands/
├── plugins/
├── tools/
├── themes/

作用：

  • Markdown 定义 agent
  • 文件级命令
  • 插件扩展

推荐入门配置

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": "notify",
  "tools": {
    "write": true,
    "bash": true
  },
  "permission": {
    "bash": "ask"
  },
  "compaction": {
    "auto": true,
    "prune": true
  }
}

总结（架构视角）

可以把 OpenCode 配置理解为四层结构：

配置层（多级 merge）
    ↓
能力层（agent / tools / mcp）
    ↓
执行层（model / provider）
    ↓
交互层（tui / server / web）

本质上，它不是简单配置文件，而是一个：

可编程 AI Agent 操作系统的配置中心