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

Использование JSON-конфигурации OpenCode.

Вы можете настроить OpenCode с помощью файла конфигурации JSON.

Формат

OpenCode поддерживает форматы JSON и JSONC (JSON с комментариями).

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  // Настройка темы
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

Расположение

Вы можете разместить конфигурацию в нескольких местах с разным порядком приоритета.

Примечание: Файлы конфигурации объединяются, а не заменяются.

Файлы конфигурации объединяются, а не заменяются. Настройки из следующих расположений комбинируются. Более поздние конфигурации переопределяют более ранние только для конфликтующих ключей. Неконфликтующие настройки из всех конфигураций сохраняются.

Например, если ваша глобальная конфигурация устанавливает theme: "opencode" и autoupdate: true, а проектная конфигурация устанавливает model: "anthropic/claude-sonnet-4-5", итоговая конфигурация будет включать все три настройки.

Порядок приоритета

Источники конфигурации загружаются в следующем порядке (более поздние источники переопределяют более ранние):

Удалённая конфигурация (из .well-known/opencode) — организационные настройки по умолчанию
Глобальная конфигурация (~/.config/opencode/opencode.json) — пользовательские предпочтения
Пользовательская конфигурация (переменная окружения OPENCODE_CONFIG) — пользовательские переопределения
Проектная конфигурация (opencode.json в проекте) — настройки для конкретного проекта
Директории .opencode — агенты, команды, плагины
Встроенная конфигурация (переменная окружения OPENCODE_CONFIG_CONTENT) — переопределения во время выполнения

Это означает, что проектные конфигурации могут переопределять глобальные настройки по умолчанию, а глобальные конфигурации могут переопределять удалённые организационные настройки по умолчанию.

Примечание: Директории .opencode и ~/.config/opencode используют множественные имена для поддиректорий: agents/, commands/, modes/, plugins/, skills/, tools/ и themes/. Единственные имена (например, agent/) также поддерживаются для обратной совместимости.

Удалённая

Организации могут предоставлять конфигурацию по умолчанию через эндпоинт .well-known/opencode. Она загружается автоматически при аутентификации у провайдера, который это поддерживает.

Удалённая конфигурация загружается первой, служа базовым слоем. Все остальные источники конфигурации (глобальная, проектная) могут переопределять эти настройки по умолчанию.

Например, если ваша организация предоставляет MCP-серверы, которые отключены по умолчанию:

Удалённая конфигурация из .well-known/opencode

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

Вы можете включить определённые серверы в вашей локальной конфигурации:

opencode.json

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Глобальная

Разместите вашу глобальную конфигурацию OpenCode в ~/.config/opencode/opencode.json. Используйте глобальную конфигурацию для пользовательских предпочтений, таких как темы, провайдеры или сочетания клавиш.

Глобальная конфигурация переопределяет удалённые организационные настройки по умолчанию.

Для проекта

Добавьте opencode.json в корень вашего проекта. Проектная конфигурация имеет наивысший приоритет среди стандартных файлов конфигурации — она переопределяет как глобальную, так и удалённую конфигурации.

Совет: Размещайте проектную конфигурацию в корне вашего проекта.

При запуске OpenCode ищет файл конфигурации в текущей директории или поднимается вверх до ближайшей директории Git.

Этот файл также безопасно добавлять в Git, и он использует ту же схему, что и глобальный.

Пользовательский путь

Укажите пользовательский путь к файлу конфигурации с помощью переменной окружения OPENCODE_CONFIG.

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Пользовательская конфигурация загружается между глобальной и проектной конфигурациями в порядке приоритета.

Пользовательская директория

Укажите пользовательскую директорию конфигурации с помощью переменной окружения OPENCODE_CONFIG_DIR. Эта директория будет просматриваться для агентов, команд, режимов и плагинов так же, как стандартная директория .opencode, и должна следовать той же структуре.

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

Пользовательская директория загружается после глобальной конфигурации и директорий .opencode, поэтому она может переопределять их настройки.

Схема

Файл конфигурации имеет схему, определённую в opencode.ai/config.json (opens in a new tab).

Ваш редактор должен уметь выполнять валидацию и автодополнение на основе схемы.

TUI

Вы можете настроить параметры, специфичные для TUI, через опцию tui.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"
  }
}

Доступные опции:

scroll_acceleration.enabled — Включить ускорение прокрутки в стиле macOS. Имеет приоритет над scroll_speed.
scroll_speed — Пользовательский множитель скорости прокрутки (по умолчанию: 3, минимум: 1). Игнорируется, если scroll_acceleration.enabled равно true.
diff_style — Управление отображением diff. "auto" адаптируется к ширине терминала, "stacked" всегда показывает один столбец.

Узнайте больше об использовании TUI здесь.

Сервер

Вы можете настроить параметры сервера для команд opencode serve и opencode web через опцию server.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

Доступные опции:

port — Порт для прослушивания.
hostname — Имя хоста для прослушивания. Когда mdns включён и имя хоста не задано, по умолчанию используется 0.0.0.0.
mdns — Включить обнаружение сервисов mDNS. Это позволяет другим устройствам в сети обнаруживать ваш сервер OpenCode.
mdnsDomain — Пользовательское доменное имя для сервиса mDNS. По умолчанию opencode.local. Полезно для запуска нескольких экземпляров в одной сети.
cors — Дополнительные источники для разрешения CORS при использовании HTTP-сервера из браузерного клиента. Значения должны быть полными источниками (схема + хост + опциональный порт), например https://app.example.com.

Узнайте больше о сервере здесь.

Инструменты

Вы можете управлять инструментами, которые может использовать LLM, через опцию tools.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Узнайте больше об инструментах здесь.

Модели

Вы можете настроить провайдеров и модели, которые хотите использовать в конфигурации OpenCode, через опции provider, model и small_model.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Опция small_model настраивает отдельную модель для лёгких задач, таких как генерация заголовков. По умолчанию OpenCode пытается использовать более дешёвую модель, если она доступна у вашего провайдера, иначе возвращается к вашей основной модели.

Опции провайдера могут включать timeout и setCacheKey:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  }
}

timeout — Таймаут запроса в миллисекундах (по умолчанию: 300000). Установите false для отключения.
setCacheKey — Гарантировать, что ключ кэша всегда установлен для указанного провайдера.

Вы также можете настроить локальные модели. Узнайте больше.

Опции для конкретных провайдеров

Некоторые провайдеры поддерживают дополнительные опции конфигурации помимо общих настроек timeout и apiKey.

Amazon Bedrock

Amazon Bedrock поддерживает конфигурацию, специфичную для AWS:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}

region — Регион AWS для Bedrock (по умолчанию переменная окружения AWS_REGION или us-east-1)
profile — Именованный профиль AWS из ~/.aws/credentials (по умолчанию переменная окружения AWS_PROFILE)
endpoint — Пользовательский URL эндпоинта для VPC-эндпоинтов. Это псевдоним для общей опции baseURL с использованием терминологии AWS. Если указаны оба, endpoint имеет приоритет.

Примечание: Bearer-токены (AWS_BEARER_TOKEN_BEDROCK или /connect) имеют приоритет над аутентификацией на основе профиля. См. приоритет аутентификации для подробностей.

Узнайте больше о конфигурации Amazon Bedrock.

Темы

Вы можете настроить тему, которую хотите использовать в конфигурации OpenCode, через опцию theme.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "theme": ""
}

Узнайте больше здесь.

Агенты

Вы можете настроить специализированных агентов для конкретных задач через опцию agent.

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Отключить инструменты модификации файлов для агента только для ревью
        "write": false,
        "edit": false
      }
    }
  }
}

Вы также можете определять агентов с помощью markdown-файлов в ~/.config/opencode/agents/ или .opencode/agents/. Узнайте больше здесь.

Агент по умолчанию

Вы можете установить агента по умолчанию с помощью опции default_agent. Это определяет, какой агент используется, когда ни один не указан явно.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

Агент по умолчанию должен быть основным агентом (не субагентом). Это может быть встроенный агент, такой как "build" или "plan", или пользовательский агент, который вы определили. Если указанный агент не существует или является субагентом, OpenCode вернётся к "build" с предупреждением.

Эта настройка применяется ко всем интерфейсам: TUI, CLI (opencode run), десктопное приложение и GitHub Action.

Общий доступ

Вы можете настроить функцию общего доступа через опцию share.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

Принимает:

"manual" — Разрешить ручной общий доступ через команды (по умолчанию)
"auto" — Автоматически делиться новыми разговорами
"disabled" — Полностью отключить общий доступ

По умолчанию общий доступ установлен в ручной режим, где вам нужно явно делиться разговорами с помощью команды /share.

Команды

Вы можете настроить пользовательские команды для повторяющихся задач через опцию command.

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

Вы также можете определять команды с помощью markdown-файлов в ~/.config/opencode/commands/ или .opencode/commands/. Узнайте больше здесь.

Сочетания клавиш

Вы можете настроить сочетания клавиш через опцию keybinds.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {}
}

Узнайте больше здесь.

Автообновление

OpenCode автоматически загружает новые обновления при запуске. Вы можете отключить это с помощью опции autoupdate.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

Если вы не хотите обновлений, но хотите получать уведомления о новых версиях, установите autoupdate в "notify". Обратите внимание, что это работает только если OpenCode не был установлен через менеджер пакетов, такой как Homebrew.

Форматтеры

Вы можете настроить форматтеры кода через опцию formatter.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Узнайте больше о форматтерах здесь.

Разрешения

По умолчанию opencode разрешает все операции без требования явного одобрения. Вы можете изменить это с помощью опции permission.

Например, чтобы инструменты edit и bash требовали одобрения пользователя:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Узнайте больше о разрешениях здесь.

Сжатие

Вы можете управлять поведением сжатия контекста через опцию compaction.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": true
  }
}

auto — Автоматически сжимать сессию, когда контекст заполнен (по умолчанию: true).
prune — Удалять старые выводы инструментов для экономии токенов (по умолчанию: true).

Наблюдатель

Вы можете настроить паттерны игнорирования для наблюдателя файлов через опцию watcher.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Паттерны следуют синтаксису glob. Используйте это для исключения шумных директорий из наблюдения за файлами.

MCP-серверы

Вы можете настроить MCP-серверы, которые хотите использовать, через опцию mcp.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

Узнайте больше здесь.

Плагины

Плагины расширяют OpenCode пользовательскими инструментами, хуками и интеграциями.

Размещайте файлы плагинов в .opencode/plugins/ или ~/.config/opencode/plugins/. Вы также можете загружать плагины из npm через опцию plugin.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Узнайте больше здесь.

Инструкции

Вы можете настроить инструкции для используемой модели через опцию instructions.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Принимает массив путей и glob-паттернов к файлам инструкций. Узнайте больше о правилах здесь.

Отключённые провайдеры

Вы можете отключить провайдеров, которые загружаются автоматически, через опцию disabled_providers. Это полезно, когда вы хотите предотвратить загрузку определённых провайдеров, даже если их учётные данные доступны.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

Примечание: disabled_providers имеет приоритет над enabled_providers.

Опция disabled_providers принимает массив идентификаторов провайдеров. Когда провайдер отключён:

Он не будет загружен, даже если установлены переменные окружения.
Он не будет загружен, даже если API-ключи настроены через команду /connect.
Модели провайдера не появятся в списке выбора моделей.

Включённые провайдеры

Вы можете указать список разрешённых провайдеров через опцию enabled_providers. Когда установлено, только указанные провайдеры будут включены, а все остальные будут игнорироваться.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

Это полезно, когда вы хотите ограничить OpenCode использованием только определённых провайдеров, а не отключать их по одному.

Примечание: disabled_providers имеет приоритет над enabled_providers.

Если провайдер присутствует как в enabled_providers, так и в disabled_providers, disabled_providers имеет приоритет для обратной совместимости.

Экспериментальные

Ключ experimental содержит опции, которые находятся в активной разработке.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {}
}

Внимание: Экспериментальные опции нестабильны. Они могут измениться или быть удалены без предупреждения.

Переменные

Вы можете использовать подстановку переменных в файлах конфигурации для ссылки на переменные окружения и содержимое файлов.

Переменные окружения

Используйте {env:VARIABLE_NAME} для подстановки переменных окружения:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Если переменная окружения не установлена, она будет заменена пустой строкой.

Файлы

Используйте {file:path/to/file} для подстановки содержимого файла:

opencode.json

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

Пути к файлам могут быть:

Относительными к директории файла конфигурации
Или абсолютными путями, начинающимися с / или ~

Это полезно для:

Хранения конфиденциальных данных, таких как API-ключи, в отдельных файлах.
Включения больших файлов инструкций без загромождения конфигурации.
Совместного использования общих фрагментов конфигурации в нескольких файлах конфигурации.

Введение Провайдеры