务必加上 `$schema`，编辑器即可基于 [opencode.ai/config.json](https://opencode.ai/config.json) 提供校验与自动补全。TUI 专属设置使用另一套 Schema：[opencode.ai/tui.json](https://opencode.ai/tui.json)。

---

## 4.2 配置文件位置

配置可以放在多个位置，它们各自承担不同角色：

| 角色 | 路径 | 用途 |
|------|------|------|
| **全局配置** | `~/.config/opencode/opencode.json` | 用户级偏好（Provider、模型、权限等） |
| **全局 TUI** | `~/.config/opencode/tui.json` | 用户级 TUI 设置（主题、键位等） |
| **项目配置** | 项目根目录 `opencode.json` | 项目专属设置，可提交进 Git |
| **项目 TUI** | 项目根 `tui.json` | 项目专属 TUI 设置 |
| **自定义路径** | `OPENCODE_CONFIG` 环境变量指向的文件 | 自定义覆盖 |
| **自定义目录** | `OPENCODE_CONFIG_DIR` 指向的目录 | 存放 agents/commands/plugins 等 |

`.opencode/` 与 `~/.config/opencode/` 目录下使用**复数**子目录名：`agents/`、`commands/`、`modes/`、`plugins/`、`skills/`、`tools/`、`themes/`（单数名也兼容）。

启动时，OpenCode 先在当前目录找配置，再向上回溯到最近的 Git 目录。

---

## 4.3 关键机制：配置是「合并」而非「替换」

这是最容易踩坑、也最重要的一点：**多个配置文件会被合并，而不是后者整体替换前者**。只有发生冲突的键才会被后者覆盖，其余设置全部保留。

例如：全局配置设了 `autoupdate: true`，项目配置设了 `model: "anthropic/claude-sonnet-4-5"`，最终配置会**同时包含**这两项。

这意味着你可以：

- 把通用偏好（Provider、权限、主题）放全局；
- 把项目专属设置（模型、规则、命令）放项目；
- 二者自动合并，互不丢失。

---

## 4.4 优先级顺序

配置源按以下顺序加载，**后者覆盖前者的冲突键**：

1. **远程配置**（来自组织的 `.well-known/opencode`）—— 组织默认值
2. **全局配置**（`~/.config/opencode/opencode.json`）—— 用户偏好
3. **自定义配置**（`OPENCODE_CONFIG` 环境变量）—— 自定义覆盖
4. **项目配置**（项目内 `opencode.json`）—— 项目专属
5. **`.opencode` 目录**（agents / commands / plugins）
6. **内联配置**（`OPENCODE_CONFIG_CONTENT` 环境变量）—— 运行时覆盖
7. **托管配置文件**（如 macOS 的 `/Library/Application Support/opencode/`）—— 管理员控制
8. **macOS 托管偏好**（通过 MDM 下发的 `.mobileconfig`）—— 最高优先级，用户不可覆盖

简单记：**远程 < 全局 < 自定义 < 项目 < 内联 < 托管**。托管设置覆盖一切，常用于企业统一管控（详见第十章/官方 policies 文档）。

---

## 4.5 远程配置（组织默认值）

组织可以通过 `.well-known/opencode` 端点提供默认配置，在你认证某个支持该机制的 Provider 时自动拉取。它作为最底层，其它配置都能覆盖它。

典型用法：组织默认提供一批 MCP 服务器但默认禁用，你在本地按需开启：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

`attention.enabled` 可开启桌面通知与提示音，适合长任务跑完时提醒你。

> `opencode.json` 里旧的 `theme`、`keybinds`、`tui` 顶层键已废弃，会在可能时自动迁移到 `tui.json`。新配置请直接写到 `tui.json`。

可用 `OPENCODE_TUI_CONFIG` 指向自定义 TUI 配置文件。

---

## 4.7 主要配置项总览

以下是 `opencode.json` 中最常用的配置项，后续章节会逐一深入。先建立全局印象：

| 配置项 | 作用 | 相关章节 |
|--------|------|----------|
| `model` / `small_model` | 主模型 / 轻量任务模型 | 第五、九章 |
| `provider` | Provider 与模型选项（密钥、超时、缓存、推理强度等） | 第五章 |
| `enabled_providers` / `disabled_providers` | 启用 / 禁用 Provider | 第五章 |
| `agent` | 自定义 / 覆盖 Agent | 第六章 |
| `default_agent` | 默认主智能体 | 第六章 |
| `command` | 自定义命令 | 第七章 |
| `instructions` | 额外规则文件（路径 / glob / URL） | 第七章 |
| `mcp` | MCP 服务器 | 第八章 |
| `plugin` | 插件（npm 包） | 第八章 |
| `tools` | （旧）工具开关，已并入 `permission` | 第八章 |
| `permission` | 权限系统（allow/ask/deny） | 第八章 |
| `formatter` | 代码格式化器 | 第八章 |
| `lsp` | LSP 服务器 | 第八章 |
| `compaction` | 上下文压缩与裁剪 | 第九章 |
| `snapshot` | 文件快照开关 | 第九、十章 |
| `watcher` | 文件监听忽略规则 | 第九章 |
| `share` | 分享模式（manual/auto/disabled） | 本章 |
| `autoupdate` | 自动更新 | 本章 |
| `shell` | 交互终端使用的 shell | 本章 |
| `attachment` | 图片附件归一化限制 | 本章 |
| `experimental` | 实验特性（含 policies） | 第十章 |

### 分享、自动更新、Shell

```jsonc title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual",     // manual（默认，需手动 /share）| auto | disabled
  "autoupdate": true,    // true | false | "notify"（只通知不更新）
  "shell": "pwsh"        // 不写则按系统自动选择
}

### 文件内容

用 `{file:path/to/file}` 把文件内容内联进来：

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