Archivo de configuración de OpenCode

OpenCode utiliza el formato JSON para la configuración.

Podemos ver primero el archivo de configuración global~/.config/opencode/opencode.json：

touch ~/.config/opencode/opencode.json

que contiene el proveedor de modelos e información de configuración:

{
  // 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"
        }
      }
    }
  }
}

Un ejemplo de configuración mínima viable

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

Elementos de configuración global comunes:

Elemento de configuración	Tipo	Descripción
model	string	Modelo principal predeterminado
small_model	string	Modelo de tareas ligeras (como generación de títulos)
autoupdate	boolean / "notify"	Política de actualización automática
theme	string	Tema de la interfaz de usuario
provider	object	Configuración del proveedor de modelos

Ejemplo de proveedor:

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

Comprender el "mecanismo de fusión" de la configuración

La configuración de OpenCode no es de sobrescritura, sino defusión por capas。

Orden de carga (de menor a mayor)

Orden	Fuente	Descripción
1	Remoto.well-known/opencode	Configuración predeterminada de la organización
2	Configuración global	~/.config/opencode/opencode.json
3	Ruta personalizada	OPENCODE_CONFIG
4	Configuración del proyecto	En el proyectoopencode.json
5	.opencode/Directorio	Capacidad de extensión
6	Configuración en línea	OPENCODE_CONFIG_CONTENT

Reglas de fusión

• Campos sin conflicto: todos se conservan
• Campos en conflicto: el último sobrescribe al primero

Ejemplo

Configuración global:

{
  "autoupdate": true
}

Configuración del proyecto:

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

Resultado final:

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

---

Configuración del proyecto

Crear en el directorio raíz del proyecto:

opencode.json

Función:

• Definir el comportamiento de IA específico del proyecto
• Se puede enviar a Git
• Sobrescribe la configuración global

Ejemplo: Configuración a nivel de proyecto

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

---

Explicación detallada de los módulos de configuración principales

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

Modelo y Proveedor

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

Campo	Descripción
model	Modelo de tarea principal
small_model	Modelo de tareas de bajo costo

Control de herramientas

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

Herramienta	Función
write	Escribir archivo
bash	Ejecutar comando

Esto esla primera capa de control de seguridad。

Control de permisos

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

Valor	Significado
allow	Ejecución automática
ask	Confirmar cada vez
deny	Prohibido

Agente (capacidad principal)

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

Esencia:Definir el rol + el alcance de capacidades para la IA

Comando (Prompt automatizado)

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

Esencia:Sistema de plantillas de prompt

Configuración de TUI

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

Configuración del servidor (API / Web)

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

Compresión de contexto (optimización de tokens)

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

Sistema de complementos

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

MCP (ecosistema de extensiones)

{
  "mcp": {}
}

Se utiliza para conectar herramientas externas (como Jira, bases de datos, etc.)

Sistema de instrucciones (reglas de IA)

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

Control del proveedor

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

Prioridad:

disabled > enabled

Sistema de variables

Variables de entorno:

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

Referencia de archivos

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

---

Mecanismo de extensión de directorios

OpenCode no es solo configuración JSON, también admite extensión de directorios:

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

Función:

• Definir agente con Markdown
• Comandos a nivel de archivo
• Extensión de complementos

---

Configuración recomendada para comenzar

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

---

Resumen (perspectiva de arquitectura)

La configuración de OpenCode se puede entender como una estructura de cuatro capas:

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

En esencia, no es un simple archivo de configuración, sino un:

Centro de configuración de un sistema operativo de Agente de IA programable

Otras extensiones