Права доступа OpenCode 2: переход с V1 и подтверждение доступа вне проекта

Чтобы вернуть запросы доступа к внешним каталогам в OpenCode 2, добавьте правило external_directory с effect: "ask". По состоянию на 2026-10-31 официальное руководство по переходу указывает для V2 значение по умолчанию allow, а для V1 — ask. Поддерживаемую конфигурацию V1 можно оставить до переноса её правил в упорядоченный массив V2 permissions.

Ниже приведены базовые правила для интерактивной работы над кодом и порядок проверки для OpenCode v2.2.0. Ожидаемые результаты следуют из документации и исходного кода с тегом версии, а не из проверки запущенного клиента.

Почему V2 разрешает внешние пути, если при отсутствии совпадений используется ask?

OpenCode учитывает встроенные правила, поэтому отсутствие вашего правила не означает отсутствие совпадения при проверке прав.

Согласно разделу Defaults в документации V2, набор правил каждого агента начинается с общего разрешения. У него заданы action: "*", resource: "*" и effect: "allow". Следующие базовые правила требуют подтверждения чтения *.env и *.env.*, а затем разрешают чтение *.env.example. Предустановленные агенты могут добавлять ограничения.

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

Разрешение доступа к внешнему каталогу и разрешение файловой операции проверяются отдельно. В проверке участвуют активная Location и рабочее дерево проекта, если его путь не указывает на корень файловой системы. Для пути за пределами обеих областей OpenCode сначала проверяет external_directory, а затем read или edit. Здесь Location — активная рабочая область. Поэтому внешний файл может пройти проверку границы, но попасть под ограничение чтения или правок.

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

Можно ли оставить конфигурацию V1 и какие имена меняются?

Да. Формат V2 необязателен: OpenCode преобразует поддерживаемую конфигурацию V1 при загрузке, не переписывая исходные файлы. Инструкция по переходу рекомендует сначала проверить существующие модели, учётные данные, агентов, права доступа и MCP-серверы.

В V1 правила доступа сгруппированы по инструментам:

{
  "permission": {
    "bash": {
      "git push *": "ask"
    },
    "edit": "allow"
  },
  "tools": {
    "websearch": false
  }
}

Документированный вариант для V2 выражает эти явно заданные настройки через упорядоченные правила:

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

Каждое правило содержит три строковых поля: action, resource и effect. Значение allow разрешает продолжить без запроса, deny блокирует операцию, а ask ожидает решения в клиенте.

Этот пример переносит показанные настройки, но не заменяет рекомендуемый базовый набор ниже. Он по-прежнему разрешает правки и не возвращает запросы доступа к внешним каталогам.

Переименования действий: bash → shell, task → subagent, write/patch → edit. В V2 действие edit проверяет целевые пути для операций edit, write и patch. Для subagent ресурсом служит ID агента; для shell — строка команды, которую сформировал сканер. Справочник действий также указывает, что doom_loop и lsp не входят в текущий набор действий прав доступа V2 Core.

Проверьте настройки верхнего уровня, определения агентов и скрипты, которые создают конфигурацию. Не заменяйте эти слова во всех файлах подряд. После намеренного перехода не оставляйте конкурирующие определения прав в форматах V1 и V2.

Настройте базовые правила V2 с явным подтверждением

Для интерактивной работы включите подтверждение доступа вне проекта, команд оболочки и правок. Разрешите обычные проверки Git, запретите команды push по заданному шаблону и чтение файлов окружения, кроме файлов-примеров.

Настройки конкретного репозитория разместите в opencode.jsonc в корне проекта. Для настроек пользователя используйте ~/.config/opencode/opencode.jsonc. OpenCode также принимает варианты с расширением .json; поддерживаемые расположения описаны в справочнике конфигурации.

Объедините этот массив с существующей конфигурацией. Сохраните настройки провайдеров, определения агентов и действующие ограничения, а не заменяйте весь файл.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}

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

Неуказанные действия по-прежнему наследуют действующие настройки по умолчанию. Этот набор не блокирует все инструменты MCP, не гарантирует запрет всех способов выполнить push и не изолирует файловую систему хоста. Ограничения read сами по себе также не блокируют чтение тех же файлов через оболочку.

В предупреждении о shell сказано, что команды оболочки сохраняют полномочия пользователя, от имени которого работает OpenCode. Сканер может определить не все каталоги, к которым обратится команда. Проверяйте команды перед подтверждением; если файловых правил недостаточно, отдельно ограничивайте команды оболочки.

Для Claude Code используйте отдельное руководство по защите секретов и операциям Git. Не переносите туда синтаксис конфигурации OpenCode.

Размещайте исключения после правил, которые они переопределяют

Порядок важен для правил, которые совпадают с одним и тем же действием и ресурсом. Более позднее совпадение заменяет предыдущий результат. Шаблон в поле действия может охватывать несколько имён действий.

В базовом массиве правило shell: "*" сначала требует подтверждения. Следующие правила git status * и git diff * разрешают эти команды. Правило git push * запрещает соответствующие команды push.

Шаблон команды оболочки, заканчивающийся на *, также совпадает с командой без аргументов. Поэтому git status * охватывает и git status, и git status --short.

Согласно справочнику сопоставления, шаблоны проверяются по всему значению ресурса. Символ * соответствует нулю или более символам, включая /; ? соответствует одному символу. Разделители путей приводятся к прямым слешам, а в Windows регистр при сопоставлении не учитывается.

Если операция затрагивает несколько ресурсов, решение определяется в два этапа. Сначала для каждого ресурса берётся последнее совпавшее правило. Любой итоговый запрет блокирует операцию; если запретов нет, любой запрос подтверждения требует решения пользователя. Составная команда оболочки может породить несколько ресурсов. Одно разрешённое действие Git не разрешает всю составную команду.

Добавляйте доверенный внешний каталог с учётом остальных правил

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

[
  { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" }
]

Разрешение внешнего каталога поставьте после общего правила external_directory с ask. Разрешение чтения поставьте перед запретами для файлов окружения, чтобы сохранить их действие. Запрет правок поставьте после общего правила edit с ask.

Для этих действий с путями правила каталогов поддерживают обозначения домашнего каталога в начале пути, например ~/. Для ресурсов shell текст команды остаётся исходным: такой подстановки при загрузке конфигурации нет.

Запрет edit блокирует операции, которыми управляет это действие, включая инструменты write и patch. Он не запрещает изменения через оболочку. Ограничивайте команды оболочки отдельно и проверяйте каждый запрос разрешения, который может привести к изменению этих файлов.

Перенесите настройки и проверьте их на тестовых файлах

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

Проверьте предложенные изменения до применения

Сделайте резервные копии конфигурации пользователя и проекта, включая определения агентов в .opencode/agents/. В официальном списке расположений также указан каталог пользовательских определений ~/.config/opencode/agents/.

Отдельно разберитесь с плагинами, интеграциями через серверный API и настройками терминала. Руководство по переходу отмечает несовместимые изменения в этих областях.

Передайте OpenCode этот запрос. Он просит сначала показать изменения и не трогать файлы без подтверждения:

Read the official OpenCode V1 migration and V2 permissions documentation.

Inspect my global, project, and agent permission configuration.
Do not modify any files yet.

Propose native V2 permissions rules.
Preserve unrelated settings and existing restrictions.
Map bash to shell, task to subagent, and write and patch to edit where applicable.
Identify unsupported fields and competing V1/V2 definitions.
Restore external_directory approval without weakening existing deny rules.
Use the baseline's shell and edit approval rules unless existing rules are stricter.
Put environment-file denies before the .env.example exception.
Show the complete proposed diff and explain every behavior change.
Wait for approval before applying it.

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

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

После принятия изменений выполните opencode reload, чтобы перечитать конфигурацию. Команда описана в справочнике CLI; перед продолжением разберите предупреждения о конфигурации.

Проверьте правила в тестовом проекте

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

Создайте безопасные тестовые файлы в Bash:

lab=$(mktemp -d)
mkdir -p "$lab/project" "$lab/outside"
git -C "$lab/project" init -q
printf 'ordinary fixture\n' > "$lab/project/README.md"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env.example"
printf 'outside fixture\n' > "$lab/outside/fixture.txt"
cd "$lab/project"

Сохраните базовую конфигурацию в opencode.jsonc этого проекта, затем запустите opencode. Выберите build через /agents, как описано в руководстве по терминальному интерфейсу.

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

Операция агента	Ожидаемый результат проверки прав
Прочитать README.md через read	Разрешено базовым правилом чтения
Прочитать ../outside/fixture.txt через read	Запрос подтверждения доступа к внешнему каталогу; после подтверждения обычное чтение разрешено
Прочитать .env через read	Запрещено
Прочитать .env.example через read	Разрешено
Изменить README.md через edit, write или patch	Запрос подтверждения через действие edit
Выполнить git status, git status --short или git diff через shell	Разрешено
Выполнить git push через shell	Запрещено совпавшим правилом для shell
Выполнить pwd через shell	Запрос подтверждения

Перед проверкой push самостоятельно выполните git remote и убедитесь, что список пуст. Не добавляйте удалённый репозиторий. Ошибка Git об отсутствии удалённого репозитория не подтверждает, что команда заблокирована правилами доступа.

В запросах подтверждения выбирайте Allow once («Разрешить один раз»), а не Allow always («Разрешать всегда»). Сохранённые разрешения привязаны к проекту и могут убрать последующие запросы, но не отменяют настроенные запреты. Отключите автоматическое подтверждение.

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

Разберите расхождения, прежде чем ослаблять правило

Сначала проверьте загруженную конфигурацию и выбранного агента. Среди команд отладки CLI есть opencode debug config и opencode debug agents. Просматривайте их вывод локально; не передавайте учётные данные или конфиденциальные настройки.

Если запроса для внешнего пути нет, убедитесь, что цель расположена вне Location и рабочего дерева проекта. Затем проверьте сохранённые разрешения и автоматическое подтверждение. При неожиданном результате чтения убедитесь, что агент использовал read, а не shell.

Если команда Git заблокирована, проверьте ресурс, который сформировал сканер, и дополнительные подкоманды. Если .env.example не читается, проверьте, не перекрывает ли исключение более позднее правило *.env.* или дополнительная политика.

Отдельно перепроверьте своего провайдера, ID модели, аутентификацию и Base URL. В инструкции BetterToken по подключению OpenCode описана настройка пользовательского OpenAI-совместимого провайдера с адресом https://www.bettertoken.ai/v1. Такое подключение не заменяет конфигурацию прав OpenCode.

Если переход затрагивает выбор инструмента, сравните настройки и способы подключения Cursor и OpenCode. Для сравнения терминальных инструментов выполните ту же тестовую задачу с Aider и OpenCode в Git-проекте.

Что меняет исправление проверки путей в v2.2.0?

Исправление меняет способ определения файлов проекта при проверке внешних каталогов. Рекомендация задавать подтверждение явно при этом не меняется.

В примечаниях к v2.2.0 указано изменение, связанное с использованием файловой системы проекта. PR #59089 объясняет: для удалённых проектов и проектов в памяти проверка раньше обращалась к диску хоста. Автор PR уточняет, что обычные локальные проекты это не затрагивает.

Для удалённого проекта повторите проверку внешнего каталога на его реальной файловой системе. Согласно документированным настройкам V2 на 2026-10-31, для ограничения доступа за пределами проекта нужно явно задать external_directory с ask или deny.