Файл конфигурации 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"
}

Общие элементы глобальной конфигурации:

Элемент конфигурации	Type	Описание
model	string	Основная модель по умолчанию
small_model	string	Лёгкая модель для задач (например, генерация заголовков)
autoupdate	boolean / "notify"	Политика автообновления
theme	string	Тема интерфейса
provider	объект	Конфигурация провайдера моделей

Пример провайдера:

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

Понимание «механизма слияния» конфигурации

Конфигурация OpenCode не перезаписывается, а скорееПослойное слияние。

Порядок загрузки (от низкого к высокому)

Порядок	Source	Описание
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

Назначение:

• Определите поведение ИИ для конкретного проекта
• Можно закоммитить в 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"
}

Модели и провайдеры

{
  "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": {
    "code-reviewer": {
      "description": "代码审查",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer",
      "tools": {
        "write": false
      }
    }
  }
}

Суть:Определить роль + область возможностей для ИИ

Команда (автоматизированный промпт)

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

Суть:Система шаблонов промптов

Конфигурация TUI

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

Конфигурация сервера (API / Web)

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

Сжатие контекста (оптимизация токенов)

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

Система плагинов

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

MCP (экосистема расширений)

{
  "mcp": {}
}

Используется для интеграции внешних инструментов (таких как Jira, базы данных и т. д.)

Система инструкций (правила ИИ)

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

Управление провайдером

{
  "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
• Команды уровня файла
• Расширения плагинов

---

Рекомендуемая конфигурация для начала работы

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

Другие расширения