Сайт справки

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

Создайте opencode.jsonc в вашем проекте для настройки OpenCode. Добавьте схему для проверки в редакторе, затем установите только нужные параметры.

opencode.jsonc

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

Вы также можете попросить OpenCode обновить этот файл за вас.

Формат

OpenCode поддерживает JSON и JSONC. Используйте JSONC, когда вам нужны комментарии или завершающие запятые.

{
  "$schema": "https://opencode.ai/config.json",
  // Используйте эту модель по умолчанию.
  "model": "anthropic/claude-sonnet-5-5",
}

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

Разместите управляемые настройки для всей машины в системном каталоге конфигурации:

Платформа

Каталог

macOS

/Library/Application Support/opencode

Linux

/etc/opencode

Windows

%ProgramData%\opencode

Системный каталог работает как глобальный. Помимо opencode.json(c), он загружает agents/, commands/, skills/ и plugins/ для каждого пользователя на машине:

/etc/opencode/
├── opencode.json
├── agents/review.md
├── commands/release.md
└── skills/deploy/SKILL.md

На macOS OpenCode также читает управляемые настройки, которые MDM-инструменты развёртывают для домена ai.opencode.managed. Профиль, специфичный для пользователя, заменяет настройки для всей машины:

/Library/Managed Preferences/<user>/ai.opencode.managed.plist
/Library/Managed Preferences/ai.opencode.managed.plist

Управляемые настройки имеют наивысший приоритет, поэтому пользователи и проекты не могут переопределить значения, которые они устанавливают, а управляемые настройки имеют приоритет над системным каталогом. Одних настроек недостаточно, чтобы помешать пользователям добавлять провайдеров, MCP-серверы, агентов или плагины; используйте политики в управляемой конфигурации для наложения ограничений.

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

~/.config/opencode/opencode.json(c)

Разместите настройки проекта в одном из этих файлов:

/home/user/projects/my-app/opencode.json(c)
/home/user/projects/my-app/.opencode/opencode.json(c)

OpenCode ищет от текущей директории до корня файловой системы. Сначала он объединяет прямые файлы opencode.json(c) от самой далёкой директории к ближайшей, затем объединяет файлы внутри директорий .opencode в том же порядке. Это означает, что каждый обнаруженный конфиг .opencode переопределяет каждый прямой конфиг. Используйте один формат во всём дереве директорий, если вам не нужно такое поведение.

Например, запустите OpenCode из /home/user/projects/acme/packages/web:

/etc/opencode/opencode.json
~/.config/opencode/opencode.json

/home/user/projects/acme/
├── opencode.json
└── packages/
    └── web/
        ├── opencode.json
        └── src/

OpenCode применяет эти файлы от наименьшего к наивысшему приоритету:

  1. ~/.config/opencode/opencode.json
  2. /home/user/projects/acme/opencode.json
  3. /home/user/projects/acme/packages/web/opencode.json
  4. /etc/opencode/opencode.json

Конфиг пакета переопределяет совпадающие настройки из конфига репозитория, который переопределяет глобальный конфиг. Системный конфиг переопределяет все. Настройки, которые не конфликтуют, сохраняются. Политики из глобальных и проектных файлов вычисляются в обратном порядке, а системные политики имеют наивысший приоритет.

Схема

Полная схема конфигурации OpenCode доступна по адресу opencode.ai/config.json.

Добавьте поле $schema в ваш файл конфигурации для включения проверки и автодополнения в редакторах, поддерживающих JSON Schema:

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

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

Оболочка

Установите оболочку, используемую терминалом и инструментами оболочки.

 

{
  "shell": "/bin/zsh",
}

 

Модель

Установите модель по умолчанию в формате провайдер/модель. Глобальная модель по умолчанию в настоящее время не сохраняет #variant; ссылки на модели агентов и команд могут выбирать один.

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

См. руководство по моделям для выбора модели и локальных моделей.

Агент

Выберите основной агент, используемый, когда сессия не выбирает его явно.

{
  "default_agent": "build",
}

См. руководство по агентам для встроенных и пользовательских агентов.

Обновления

Управляйте проверкой обновлений из глобальной конфигурации. Установите update в "disable", чтобы пропустить их, "notify", чтобы показывать доступные обновления перед установкой, или "auto", чтобы устанавливать обновления автоматически. При отсутствии update по умолчанию равно "notify".

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

{
  "update": "notify",
}

Имя пользователя

Установите имя пользователя. OpenCode принимает это поле, но не отображает его в разговорах.

{
  "username": "alice",
}

Разрешения

Определите упорядоченные правила, которые разрешают, запрещают или спрашивают перед тем, как агент использует инструмент на совпадающем ресурсе.

{
  "permissions": [
    {
      "action": "shell",
      "resource": "git push *",
      "effect": "ask",
    },
  ],
}

См. руководство по разрешениям для сопоставления правил и доступных действий.

Политики

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

{
  "policies": [
    { "action": "provider.use", "resource": "*", "effect": "deny" },
    { "action": "provider.use", "resource": "anthropic", "effect": "allow" },
    { "action": "tool.use", "resource": "shell:git push *", "effect": "deny" },
  ],
}

См. руководство по политикам для сопоставления, приоритета между файлами конфигурации и управляемой политикой Console.

Агенты

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

{
  "agents": {
    "reviewer": {
      "description": "Проверяйте изменения без редактирования файлов",
      "mode": "subagent",
      "system": "Сосредоточьтесь на правильности, безопасности и отсутствующих тестах.",
      "permissions": [{ "action": "edit", "resource": "*", "effect": "deny" }],
    },
  },
}

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

Снимки

Включите или отключите снимки файловой системы, используемые для отмены и восстановления.

{
  "snapshots": false,
}

См. руководство по снимкам для поведения отмены и повтора.

Наблюдатель

Игнорируйте файлы и директории, которые не должны вызывать обновления файловой системы.

{
  "watcher": {
    "ignore": ["dist/**", "coverage/**"],
  },
}

Форматтер

Форматируйте файлы после того, как инструменты write, edit или patch изменяют их. Установите formatter в true, чтобы включить доступные встроенные форматтеры.

{
  "formatter": true,
}

См. руководство по форматтерам для встроенных и пользовательских форматтеров.

Медиа

Управляйте тем, как изображения, загружаемые инструментом read, изменяют размер или отклоняются перед отправкой модели.

{
  "media": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880,
    },
  },
}

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

Вывод

Установите максимальное количество строк и байт, сохраняемых из результата инструмента.

{
  "tool_output": {
    "max_lines": 2000,
    "max_bytes": 51200,
  },
}

Поиск

Выберите, как OpenCode ищет в вебе. Используйте "random", чтобы автоматически выбрать доступного провайдера.

{
  "websearch": {
    "provider": "random",
  },
}

См. руководство по веб-поиску для провайдеров, учётных данных, выбора, ограничений частоты запросов и отключения поиска.

MCP

Настройте локальные и удалённые серверы Model Context Protocol. Глобальные значения mcp.timeout применяются к серверам, определённым в файлах конфигурации; каждый сервер переопределяет их своим timeout.

{
  "mcp": {
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["bunx", "@playwright/mcp"],
      },
    },
  },
}

См. руководство по MCP для удалённых серверов, OAuth, переменных окружения и таймаутов.

Компактизация

Управляйте автоматической компактизацией контекста и тем, сколько недавнего контекста она сохраняет.

{
  "compaction": {
    "auto": true,
    "keep": {
      "tokens": 15000,
    },
    "buffer": 20000,
  },
}

Локальные сводки остаются по умолчанию. Подключите нативную компактизацию провайдера для обоих автоматических и ручных запросов с помощью политики провайдера или модели:

{
  "providers": {
    "openai": {
      "settings": { "compaction": { "type": "native" } },
      "models": {
        "gpt-6.1-sol": { "settings": { "compaction": { "type": "summary" } } },
      },
    },
  },
}

Настройка модели переопределяет настройку провайдера. Автоматическая компактизация использует доступный бюджет ввода выбранной модели. Контрольные точки провайдера сохраняют недавние сообщения пользователя в пределах того же бюджета compaction.keep.tokens, который локальные сводки используют для сохраняемого хвоста. compaction.auto: false на верхнем уровне отключает новую автоматическую компактизацию без удаления установленных контрольных точек. См. руководство по компактизации для бюджетирования и восстановления при переполнении.

Прогрев

Поддерживайте недавно активные сессии модели в активном состоянии с помощью периодических временных запросов. Прогрев отключён по умолчанию; установите true, чтобы использовать четырёхминутный интервал простоя и 30-минутное активное окно.

{
  "warming": {
    "prompt": "Не выполняйте никакой работы. Ответьте ровно: OK",
    "interval": "4 minutes",
    "duration": "30 minutes",
  },
}

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

Навыки

Добавьте директории или URL, которые OpenCode должен использовать для поиска навыков агентов.

{
  "skills": ["./team-skills", "https://example.com/.well-known/skills/"],
}

См. руководство по навыкам для структуры навыков и автоматического обнаружения в .opencode/skills/.

Команды

Определите повторно используемые слэш-команды как именованные шаблоны запросов.

{
  "commands": {
    "review": {
      "description": "Проверить текущие изменения",
      "template": "Проверьте текущий дифф на правильность и отсутствующие тесты.",
    },
  },
}

См. руководство по командам для аргументов, моделей, агентов и файловых команд.

Инструкции

Объявите дополнительные файлы инструкций, маски имён файлов или HTTP(S) URL. OpenCode загружает их вместе с обнаруженными файлами AGENTS.md.

 

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

 

См. руководство по инструкциям для проектных инструкций и AGENTS.md.

Ссылки

Сделайте локальные директории или Git-репозитории доступными как именованный вспомогательный контекст.

{
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Поведение продукта и терминология",
    },
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

См. руководство по ссылкам для сокращений, видимости и разрешения путей.

Рабочие деревья

Установите родительскую директорию для новых локальных рабочих деревьев. OpenCode добавляет запрошенное или сгенерированное имя рабочего дерева.

{
  "worktree": {
    "directory": "../worktrees",
  },
}

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

Например, эта глобальная конфигурация размещает новые рабочие деревья в .lane/trees/ каждого проекта:

{
  "worktree": {
    "directory": ".lane/trees",
  },
}

Без этой настройки создание использует каталог данных сервера в worktree/<первые-шесть-символов-ID-проекта>. Создание и обновление рабочего дерева загружают конфигурацию из сохранённой канонической проверки проекта, включая когда другие клоны разделяют его ID проекта. Изменение не перемещает существующие рабочие деревья.

Git — встроенный по умолчанию. Плагин, регистрирующий стратегию, автоматически становится по умолчанию в рантайме этого плагина. Проекты используют рантайм канонической проверки. Параметры, специфичные для стратегии, принадлежат этому плагину, а не объекту конфигурации worktree.

Плагины

Загружайте плагины из пакетов или локальных директорий плагинов. Используйте объектную форму, когда плагин принимает параметры.

{
  "plugins": [
    "opencode-example-plugin",
    {
      "package": "./plugins/local",
      "options": {
        "enabled": true,
      },
    },
  ],
}

См. руководство по плагинам для загрузки и конфигурации плагинов.

Провайдеры

Настройте провайдеры и добавьте или переопределите их модели, настройки запросов, заголовки и варианты моделей.

{
  "providers": {
    "openai": {
      "models": {
        "gpt-6.1-sol-custom": {
          "modelID": "gpt-6.1-sol",
          "name": "GPT-6.1 Sol Custom",
          "limit": {
            "context": 200000,
            "output": 32000,
          },
        },
      },
    },
  },
}

settings.transport: "websocket" провайдера выбирает его WebSocket-сессию.

См. руководство по провайдерам для учётных данных, пользовательских конечных точек, пакетов провайдеров, транспорта WebSocket и настройки моделей.

Переменные

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

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

Используйте {env:ИМЯ_ПЕРЕМЕННОЙ} для подстановки переменных окружения:

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

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

Файлы

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

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "openai": {
      "settings": {
        "apiKey": "{file:~/.secrets/openai-key}",
      },
    },
  },
}

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

  • Относительными относительно директории файла конфигурации
  • Абсолютными или начинающимися с ~/ для вашей домашней директории

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

Они полезны для:

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

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

Все экспериментальные настройки находятся под ключом experimental:

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "todo": true,
    "subagent_depth": 2,
    "portable_shell_scanner": true,
    "background_compaction": true,
    "location_idle_timeout": "4 hours",
  },
}

Задачи

Установите todo в true, чтобы дать агентам инструмент todowrite для отслеживания многошаговой работы. По умолчанию false.

Глубина подагента

subagent_depth устанавливает, насколько глубоко подагенты могут запускать свои собственные подагенты. По умолчанию 1, поэтому подагент не может запустить другой подагент.

Переносной сканер оболочек

Установите portable_shell_scanner в true, чтобы заменить встроенный сканер tree-sitter для оболочек, используемый проверками разрешений. По умолчанию false. См. Разрешения для того, как он работает.

Фоновая компактизация

Установите background_compaction в true, чтобы записывать сводку компактизации в фоне до того, как она понадобится, чтобы автоматическая компактизация не приостанавливала сессию. По умолчанию false. См. Компактизация для того, как это работает.

{
  "experimental": {
    "background_compaction": true,
  },
}

Таймаут простоя местоположения

location_idle_timeout управляет тем, как долго местоположение проекта может оставаться без активности сессии, прежде чем OpenCode выгрузит его сервисы. Принимает длительность, например "2 hours", по умолчанию "60 minutes". Работающие сессии и фоновые задачи поддерживают местоположение загруженным. Установите false, чтобы никогда не выгружать простаивающие местоположения. Конфиг проекта может переопределить глобальное значение.

{
  "experimental": {
    "location_idle_timeout": false,
  },
}

Устаревшие политики

experimental.policies устарел. Используйте верхнеуровневые policies вместо него. Старый ключ всё ещё работает и объединяется с policies.

Наверх

© Сайт справки 2026