opencode config.json说明

# OpenCode 配置文档

本文档详细说明了 OpenCode 的所有配置选项，基于 `config.json` 的 JSON Schema 定义。

## 目录

- [全局配置](#全局配置)
- [服务器配置](#服务器配置)
- [命令配置](#命令配置)
- [技能配置](#技能配置)
- [文件监视器配置](#文件监视器配置)
- [快照配置](#快照配置)
- [插件配置](#插件配置)
- [分享配置](#分享配置)
- [更新配置](#更新配置)
- [提供商配置](#提供商配置)
- [模型配置](#模型配置)
- [代理配置](#代理配置)
- [MCP 配置](#mcp-配置)
- [格式化器配置](#格式化器配置)
- [LSP 配置](#lsp-配置)
- [指令配置](#指令配置)
- [权限配置](#权限配置)
- [压缩配置](#压缩配置)
- [实验性功能](#实验性功能)

---

## 全局配置

### `$schema`

- **类型**: `string`
- **描述**: JSON Schema 引用，用于配置验证
- **默认值**: `"https://json-schema.org/draft/2020-12/schema"`

### `logLevel`

- **类型**: `string`
- **描述**: 日志级别
- **可选值**:
  - `DEBUG` - 调试信息
  - `INFO` - 一般信息
  - `WARN` - 警告信息
  - `ERROR` - 错误信息
- **默认值**: `INFO`

---

## 服务器配置

### `server`

服务器配置，用于 `opencode serve` 和 `web` 命令。

#### `server.port`

- **类型**: `integer`
- **描述**: 监听的端口号
- **约束**: 大于 0，小于 9007199254740991

#### `server.hostname`

- **类型**: `string`
- **描述**: 监听的主机名

#### `server.mdns`

- **类型**: `boolean`
- **描述**: 启用 mDNS 服务发现

#### `server.mdnsDomain`

- **类型**: `string`
- **描述**: mDNS 服务的自定义域名（默认为 `opencode.local`）

#### `server.cors`

- **类型**: `array of string`
- **描述**: 允许 CORS 的额外域名列表

---

## 命令配置

### `command`

命令配置，详见 [https://opencode.ai/docs/commands](https://opencode.ai/docs/commands)

每个自定义命令可以包含以下属性：

#### `command.[name].template`

- **类型**: `string`
- **描述**: 命令模板（必需）

#### `command.[name].description`

- **类型**: `string`
- **描述**: 命令描述

#### `command.[name].agent`

- **类型**: `string`
- **描述**: 使用的代理

#### `command.[name].model`

- **类型**: `string`
- **描述**: 使用的模型（格式：`provider/model`）

#### `command.[name].subtask`

- **类型**: `boolean`
- **描述**: 是否作为子任务执行

---

## 技能配置

### `skills`

额外的技能文件夹配置。

#### `skills.paths`

- **类型**: `array of string`
- **描述**: 额外的技能文件夹路径

#### `skills.urls`

- **类型**: `array of string`
- **描述**: 从 URL 获取技能（例如：`https://example.com/.well-known/skills/`）

---

## 文件监视器配置

### `watcher`

#### `watcher.ignore`

- **类型**: `array of string`
- **描述**: 要忽略的文件或目录模式列表

---

## 快照配置

### `snapshot`

- **类型**: `boolean`
- **描述**: 启用或禁用快照跟踪。当为 `false` 时，文件系统快照不会被记录，撤销或恢复操作将不会撤销/重做文件更改
- **默认值**: `true`

---

## 插件配置

### `plugin`

- **类型**: `array`
- **描述**: 插件列表

每个插件可以是：
- `string` - 插件名称
- `array` - `[插件名称, 配置对象]`

---

## 分享配置

### `share`

- **类型**: `string`
- **描述**: 控制分享行为
- **可选值**:
  - `manual` - 允许通过命令手动分享
  - `auto` - 启用自动分享
  - `disabled` - 禁用所有分享

### `autoshare`

- **类型**: `boolean`
- **描述**: **已弃用**，请使用 `share` 字段。自动分享新创建的会话

---

## 更新配置

### `autoupdate`

- **类型**: `boolean | string`
- **描述**: 自动更新到最新版本
  - `true` - 自动更新
  - `false` - 禁用
  - `"notify"` - 显示更新通知

---

## 提供商配置

### `disabled_providers`

- **类型**: `array of string`
- **描述**: 禁用自动加载的提供商

### `enabled_providers`

- **类型**: `array of string`
- **描述**: 当设置时，**仅**启用这些提供商。所有其他提供商将被忽略

---

## 模型配置

### `model`

- **类型**: `string`
- **描述**: 使用的模型，格式为 `provider/model`，例如 `anthropic/claude-2`

### `small_model`

- **类型**: `string`
- **描述**: 用于任务（如标题生成）的小模型，格式为 `provider/model`

---

## 代理配置

### `default_agent`

- **类型**: `string`
- **描述**: 未指定代理时使用的默认代理。必须是主要代理。如果未设置或指定的代理无效，则回退到 `build`

### `username`

- **类型**: `string`
- **描述**: 在对话中显示的自定义用户名（代替系统用户名）

### `agent`

代理配置，详见 [https://opencode.ai/docs/agents](https://opencode.ai/docs/agents)

每个代理可包含以下属性：

#### 代理通用属性

##### `model`

- **类型**: `string`
- **描述**: 代理使用的模型（格式：`provider/model`）

##### `variant`

- **类型**: `string`
- **描述**: 此代理的默认模型变体（仅在使用代理配置的模型时应用）

##### `temperature`

- **类型**: `number`
- **描述**: 模型温度参数

##### `top_p`

- **类型**: `number`
- **描述**: 模型 top_p 参数

##### `prompt`

- **类型**: `string`
- **描述**: 自定义提示词

##### `disable`

- **类型**: `boolean`
- **描述**: 禁用此代理

##### `description`

- **类型**: `string`
- **描述**: 代理的使用时机说明

##### `mode`

- **类型**: `string`
- **描述**: 代理模式
- **可选值**:
  - `subagent` - 子代理
  - `primary` - 主要代理
  - `all` - 所有模式

##### `hidden`

- **类型**: `boolean`
- **描述**: 从 @ 自动完成菜单中隐藏此子代理（默认：`false`，仅适用于 `mode: subagent`）

##### `color`

- **类型**: `string`
- **描述**: 十六进制颜色代码（如 `#FF5733`）或主题颜色（如 `primary`）
  - 主题颜色选项：`primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info`

##### `steps`

- **类型**: `integer`
- **描述**: 强制纯文本响应前的最大代理迭代次数
- **约束**: 大于 0，小于 9007199254740991

##### `maxSteps`

- **类型**: `integer`
- **描述**: **已弃用**，请使用 `steps` 字段

##### `options`

- **类型**: `object`
- **描述**: 代理的额外选项

##### `permission`

- **类型**: `object | string`
- **描述**: 代理的权限配置（详见[权限配置](#权限配置)）

##### `tools`

- **类型**: `object`
- **描述**: **已弃用**，请使用 `permission` 字段

---

## MCP 配置

### `mcp`

模型上下文协议（MCP）服务器配置

#### 本地 MCP 服务器配置

##### `mcp.[name].type`

- **类型**: `string`
- **描述**: MCP 服务器连接类型
- **值**: `"local"`

##### `mcp.[name].command`

- **类型**: `array of string`
- **描述**: 运行 MCP 服务器的命令和参数（必需）

##### `mcp.[name].environment`

- **类型**: `object`
- **描述**: 运行 MCP 服务器时设置的环境变量

##### `mcp.[name].enabled`

- **类型**: `boolean`
- **描述**: 启动时启用或禁用 MCP 服务器

##### `mcp.[name].timeout`

- **类型**: `integer`
- **描述**: MCP 服务器请求的超时时间（毫秒）。默认为 5000（5秒）

#### 远程 MCP 服务器配置

##### `mcp.[name].type`

- **类型**: `string`
- **值**: `"remote"`

##### `mcp.[name].url`

- **类型**: `string`
- **描述**: 远程 MCP 服务器的 URL（必需）

##### `mcp.[name].enabled`

- **类型**: `boolean`
- **描述**: 启动时启用或禁用 MCP 服务器

##### `mcp.[name].headers`

- **类型**: `object`
- **描述**: 请求时发送的标头

##### `mcp.[name].oauth`

- **类型**: `object | boolean`
- **描述**: MCP 服务器的 OAuth 认证配置。设置为 `false` 以禁用 OAuth 自动检测

###### `oauth.clientId`

- **类型**: `string`
- **描述**: OAuth 客户端 ID。如果未提供，将尝试动态客户端注册（RFC 7591）

###### `oauth.clientSecret`

- **类型**: `string`
- **描述**: OAuth 客户端密钥（如果授权服务器需要）

###### `oauth.scope`

- **类型**: `string`
- **描述**: 授权期间请求的 OAuth 范围

##### `mcp.[name].timeout`

- **类型**: `integer`
- **描述**: MCP 服务器请求的超时时间（毫秒）。默认为 5000（5秒）

---

## 格式化器配置

### `formatter`

代码格式化器配置

可以是：
- `false` - 禁用格式化器
- `object` - 格式化器配置对象

#### `formatter.[name].disabled`

- **类型**: `boolean`
- **描述**: 禁用此格式化器

#### `formatter.[name].command`

- **类型**: `array of string`
- **描述**: 格式化器命令和参数

#### `formatter.[name].environment`

- **类型**: `object`
- **描述**: 运行格式化器的环境变量

#### `formatter.[name].extensions`

- **类型**: `array of string`
- **描述**: 此格式化器适用的文件扩展名

---

## LSP 配置

### `lsp`

语言服务器协议（LSP）配置

可以是：
- `false` - 禁用 LSP
- `object` - LSP 配置对象

#### `lsp.[name].disabled`

- **类型**: `boolean`
- **描述**: 禁用此 LSP 服务器

#### `lsp.[name].command`

- **类型**: `array of string`
- **描述**: LSP 服务器命令和参数（必需）

#### `lsp.[name].extensions`

- **类型**: `array of string`
- **描述**: 此 LSP 服务器适用的文件扩展名

#### `lsp.[name].env`

- **类型**: `object`
- **描述**: LSP 服务器的环境变量

#### `lsp.[name].initialization`

- **类型**: `object`
- **描述**: LSP 服务器的初始化选项

---

## 指令配置

### `instructions`

- **类型**: `array of string`
- **描述**: 要包含的额外指令文件或模式

---

## 布局配置

### `layout`

- **类型**: `string`
- **描述**: **已弃用**，始终使用 stretch 布局
- **可选值**:
  - `auto`
  - `stretch`

---

## 权限配置

### `permission`

权限配置，控制各个工具和操作的权限级别

可以是：
- `object` - 详细权限配置对象
- `string` -应用于所有操作的全局权限级别

#### 权限操作配置

每个权限操作可以配置为：

##### 简单权限（字符串）

- **类型**: `string`
- **可选值**:
  - `ask` - 询问用户
  - `allow` - 允许操作
  - `deny` - 拒绝操作

##### 详细权限（对象）

- **类型**: `object`
- **描述**: 按对象细分的权限配置

#### 支持的操作权限

以下操作支持权限配置：

| 操作 | 描述 |
|------|------|
| `read` | 读取文件 |
| `edit` | 编辑文件 |
| `glob` | 文件模式匹配 |
| `grep` | 内容搜索 |
| `list` | 列出目录 |
| `bash` | 执行 bash 命令 |
| `task` | 启动子代理 |
| `external_directory` | 访问外部目录 |
| `todowrite` | 写入待办事项 |
| `question` | 询问用户 |
| `webfetch` | 获取网页内容 |
| `websearch` - 网页搜索 |
| `codesearch` | 代码搜索 |
| `lsp` | 语言服务器协议操作 |
| `doom_loop` | 循环检测 |
| `skill` | 技能加载 |

#### 权限配置示例

```json
{
  "permission": {
    "read": "allow",
    "edit": "ask",
    "bash": {
      "npm": "allow",
      "rm": "deny"
    }
  }
}
```

---

## 压缩配置

### `compaction`

上下文压缩配置

#### `compaction.auto`

- **类型**: `boolean`
- **描述**: 当上下文已满时启用自动压缩（默认：`true`）

#### `compaction.prune`

- **类型**: `boolean`
- **描述**: 启用旧工具输出的修剪（默认：`true`）

#### `compaction.reserved`

- **类型**: `integer`
- **描述**: 压缩的令牌缓冲区。保留足够的窗口以避免压缩期间的溢出
- **约束**: 大于等于 0，小于 9007199254740991

---

## 实验性功能

### `experimental`

实验性功能配置

#### `experimental.disable_paste_summary`

- **类型**: `boolean`
- **描述**: 禁用粘贴摘要

#### `experimental.batch_tool`

- **类型**: `boolean`
- **描述**: 启用批处理工具

#### `experimental.openTelemetry`

- **类型**: `boolean`
- **描述**: 为 AI SDK 调用启用 OpenTelemetry 跨度（使用 `experimental_telemetry` 标志）

#### `experimental.primary_tools`

- **类型**: `array of string`
- **描述**: 应仅对主要代理可用的工具

#### `experimental.continue_loop_on_deny`

- **类型**: `boolean`
- **描述**: 当工具调用被拒绝时继续代理循环

#### `experimental.mcp_timeout`

- **类型**: `integer`
- **描述**: 模型上下文协议（MCP）请求的超时时间（毫秒）
- **约束**: 大于 0，小于 9007199254740991

---

## 配置示例

完整的配置示例：

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "logLevel": "INFO",
  "server": {
    "port": 8080,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "opencode.local",
    "cors": ["http://localhost:3000"]
  },
  "model": "anthropic/claude-3-opus-20240229",
  "small_model": "anthropic/claude-3-haiku-20240307",
  "default_agent": "build",
  "share": "manual",
  "autoupdate": "notify",
  "snapshot": true,
  "watcher": {
    "ignore": ["node_modules", ".git", "dist"]
  },
  "skills": {
    "paths": ["/path/to/custom/skills"],
    "urls": ["https://example.com/.well-known/skills/"]
  },
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    }
  },
  "permission": {
    "read": "allow",
    "edit": "ask",
    "bash": {
      "git": "allow",
      "npm": "ask"
    }
  },
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 1000
  }
}
```

---

## 配置文件位置

配置文件的默认位置通常为：
- 项目根目录：`./kilo.json` 或 `./config.json`
- 用户配置目录：`~/.config/kilo/config.json`

配置文件支持注释和尾随逗号。

---

## 相关文档

- [命令文档](https://opencode.ai/docs/commands)
- [代理文档](https://opencode.ai/docs/agents)
- [权限系统文档](https://opencode.ai/docs/permissions)
- [MCP 文档](https://modelcontextprotocol.io/)


操作	描述
`read`	读取文件
`edit`	编辑文件
`glob`	文件模式匹配
`grep`	内容搜索
`list`	列出目录
`bash`	执行 bash 命令
`task`	启动子代理
`external_directory`	访问外部目录
`todowrite`	写入待办事项
`question`	询问用户
`webfetch`	获取网页内容
`websearch` - 网页搜索
`codesearch`	代码搜索
`lsp`	语言服务器协议操作
`doom_loop`	循环检测
`skill`	技能加载

opencode config.json说明 #50

Description

OpenCode 配置文档

目录

全局配置

$schema

logLevel

服务器配置

server

server.port

server.hostname

server.mdns

server.mdnsDomain

server.cors

命令配置

command

command.[name].template

command.[name].description

command.[name].agent

command.[name].model

command.[name].subtask

技能配置

skills

skills.paths

skills.urls

文件监视器配置

watcher

watcher.ignore

快照配置

snapshot

插件配置

plugin

分享配置

share

autoshare

更新配置

autoupdate

提供商配置

disabled_providers

enabled_providers

模型配置

model

small_model

代理配置

default_agent

username

agent

代理通用属性

model

variant

temperature

top_p

prompt

disable

description

mode

hidden

color

steps

maxSteps

options

permission

tools

MCP 配置

mcp

本地 MCP 服务器配置

mcp.[name].type

mcp.[name].command

mcp.[name].environment

mcp.[name].enabled

mcp.[name].timeout

远程 MCP 服务器配置

mcp.[name].type

mcp.[name].url

mcp.[name].enabled

mcp.[name].headers

mcp.[name].oauth

oauth.clientId

oauth.clientSecret

oauth.scope

`$schema`

`logLevel`

`server`

`server.port`

`server.hostname`

`server.mdns`

`server.mdnsDomain`

`server.cors`

`command`

`command.[name].template`

`command.[name].description`

`command.[name].agent`

`command.[name].model`

`command.[name].subtask`

`skills`

`skills.paths`

`skills.urls`

`watcher`

`watcher.ignore`

`snapshot`

`plugin`

`share`

`autoshare`

`autoupdate`

`disabled_providers`

`enabled_providers`

`model`

`small_model`

`default_agent`

`username`

`agent`

`model`

`variant`

`temperature`

`top_p`

`prompt`

`disable`

`description`

`mode`

`hidden`

`color`

`steps`

`maxSteps`

`options`

`permission`

`tools`

`mcp`

`mcp.[name].type`

`mcp.[name].command`

`mcp.[name].environment`

`mcp.[name].enabled`

`mcp.[name].timeout`

`mcp.[name].type`

`mcp.[name].url`

`mcp.[name].enabled`

`mcp.[name].headers`

`mcp.[name].oauth`

`oauth.clientId`

`oauth.clientSecret`

`oauth.scope`

`mcp.[name].timeout`

`formatter`

`formatter.[name].disabled`

`formatter.[name].command`

`formatter.[name].environment`

`formatter.[name].extensions`

`lsp`

`lsp.[name].disabled`

`lsp.[name].command`

`lsp.[name].extensions`

`lsp.[name].env`

`lsp.[name].initialization`

`instructions`

`layout`

`permission`

`compaction`

`compaction.auto`

`compaction.prune`

`compaction.reserved`

`experimental`