Настройка разрешений OpenCode

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

Начиная с v1.1.1, стараяtoolsконфигурация boolean объявлена устаревшей и объединена вpermission. Старая конфигурация всё ещё поддерживается для обратной совместимости, но рекомендуется перейти на новыйpermissionсинтаксис.

Три действия с разрешениями

Каждое правило разрешений в итоге сводится к одному из следующих трёх действий:

Действие Эффект Применимые сценарии
"allow" Выполняется автоматически без одобрения Низкорисковые, часто выполняемые операции, такие как чтение файлов и запуск тестов
"ask" Показывает запрос на одобрение, чтобы вы решили, разрешить ли Операции с некоторым риском, такие как запись файлов и выполнение скриптов
"deny" Блокируются напрямую: не выполняются и не выводят запрос на подтверждение Опасные операции, которые явно запрещены, такие как удаление файлов и отправка кода

Базовая конфигурация

Конфигурация разрешений записывается в корневом каталоге репозитория (или каталоге пользовательской конфигурации) вopencode.jsonфайле, используяpermissionполе для настройки.

1. Установить все разрешения глобально

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

Пример

{
  "$schema": "https://opencode.ai/config.json",
"permission": "allow" // Все операции выполняются автоматически без каких-либо запросов (подходит для локальной разработки, когда полностью доверяете ИИ)
}

2. Настроить по имени инструмента

Используя синтаксис объекта, вы можете отдельно указать разрешения для разных инструментов."*"является подстановочным знаком, означающим, что он соответствует всем операциям, обычно используется как резервное значение по умолчанию:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask", // Резервное правило: все инструменты, не настроенные отдельно, по умолчанию показывают запрос
"bash": "allow", // bash (выполнение команд Shell): разрешить напрямую, без запроса
"edit": "deny" // edit (изменение файлов): блокировать напрямую
  }
}

Детализированные правила (синтаксис объекта)

Для большинства разрешений, помимо установки единого действия, вы также можете использоватьсинтаксис объекта, чтобы применять разные правила в зависимости от конкретного ввода инструмента. Например, дляbashинструментов можно различать, какие команды разрешены, какие требуют подтверждения, а какие отклоняются напрямую:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
"*": "ask", // Резервный вариант: все команды bash по умолчанию требуют подтверждения
"git *": "allow", // Команды, начинающиеся с git (например, git status, git log), разрешены напрямую
"npm *": "allow", // Команды, начинающиеся с npm (например, npm install, npm run build), разрешены напрямую
"grep *": "allow", // Команды поиска grep разрешены напрямую
"rm *": "deny" // Команды удаления rm блокируются напрямую (чтобы предотвратить случайное удаление файлов)
    },
    "edit": {
"*": "deny", // По умолчанию блокировать все изменения файлов
"packages/web/src/content/docs/*.mdx": "allow" // Разрешить редактирование только файлов .mdx в каталоге docs
    }
  }
}

Порядок сопоставления правил: последнее совпавшее правило имеет приоритет.Рекомендуется размещать подстановочное"*"правило в начале как значение по умолчанию, а более конкретные правила размещайте после него, чтобы переопределить его. Таким образом, чем конкретнее правило, тем выше его приоритет, что делает логику ясной и менее подверженной ошибкам.

Правила с подстановочными знаками

Шаблоны разрешений поддерживают простое сопоставление с подстановочными знаками со следующими правилами:

Подстановочный знак Значение Пример
* Совпадает с нулём или более произвольными символами (не пересекая каталоги) git *Совпаденияgit status、git log --onelineожидание
** Совпадает с любым путём с переходом через каталоги ~/projects/**Совпадает со всеми файлами и подкаталогами в projects
? Точно совпадает с одним произвольным символом file?.txtСовпаденияfile1.txt、fileA.txt
Другие символы Совпадает точно по литеральному значению git statusСовпадает толькоgit status, не соответствует вариантам с параметрами

Примечание:Для команд с параметрами обязательно добавляйте в конце*. Например"grep *"может совпадатьgrep pattern file.txt, если написать отдельно"grep"совпадает только с командами без параметров, что почти никогда не встретится при реальном выполнении.

Развёртывание домашнего каталога

В начале шаблона можно использовать~или$HOMEчтобы сослаться на домашний каталог текущего пользователя, и OpenCode автоматически развернёт его в полный путь:

Пример

// Следующие три формы дают одинаковый результат, все разворачиваются в /Users/username/projects/* (путь зависит от системы)
"~/projects/*"
"$HOME/projects/*"
"/Users/username/projects/*" // Прямая запись абсолютного пути тоже работает, но не рекомендуется (недостаточно переносимо)

Разрешения для внешних каталогов (external_directory)

По умолчанию OpenCode разрешает инструментам доступ только крабочему каталогу при запускеи его подкаталогам. Если вам нужно получить доступ к путям вне каталога проекта (например, к другому проекту или общему каталогу конфигурации), необходимо использоватьexternal_directoryявное разрешение.

Раскрытие домашнего каталога (~/...) — это лишьсокращённое обозначение пути, и оно не даёт автоматического разрешения на доступ к этому пути. Пути вне рабочего каталога всё ещё должны проходить черезexternal_directoryчтобы получить разрешение.

1. Разрешить доступ к внешним каталогам

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow" // Разрешить доступ ко всем файлам и подкаталогам в ~/projects/personal/
// ** соответствует подпутям на любом уровне
    }
  }
}

2. Разрешить чтение, но запретить редактирование

С помощьюexternal_directoryАвторизованные каталоги наследуют разрешения по умолчанию текущего рабочего пространства. Посколькуreadпо умолчанию имеет значение"allow", после авторизации файлы в этом каталоге можно читать. Если нужно дополнительно ограничить определённую операцию (например, разрешить чтение, но запретить редактирование), можно добавить дополнительные правила:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow" // Шаг 1: Предоставить доступ к этому внешнему каталогу
    },
    "edit": {
"~/projects/personal/**": "deny" // Шаг 2: Добавить переопределяющее правило для этого каталога, разрешающее чтение, но запрещающее редактирование
    }
  }
}

Все доступные элементы разрешений

В разрешениях OpenCode в качестве ключей используются имена инструментов, охватывающие все типы, включая файловые операции, выполнение команд и сетевой доступ:

Элемент разрешения Контролируемая операция Содержимое для сопоставления по шаблону Значение по умолчанию
read Чтение содержимого файла Путь к файлу (например,src/index.js） allow（.envфайлы исключены)
edit Все изменения файлов, включая edit, write, patch и multiedit Путь к файлу allow
glob Поиск файлов по glob-шаблону (например, найти все.tsфайлы) Шаблон glob (например,**/*.ts） allow
grep Поиск текста в содержимом файлов Шаблон регулярного выражения allow
list Перечислить файлы в каталоге Путь к каталогу allow
bash Выполнить команду оболочки Разобранная полная команда (например,git status --porcelain） allow
task Запустить субагента Имя типа субагента allow
skill Загрузить навык Название навыка allow
lsp Выполнить запрос языковой службы LSP Детальная настройка в настоящее время не поддерживается allow
webfetch Получить содержимое сетевого URL Полный URL (например,https://example.com/api） allow
websearch Веб-поиск Строка поискового запроса allow
codesearch Поиск по коду Строка поискового запроса allow
external_directory Доступ к путям за пределами рабочего каталога Путь к внешнему каталогу ask
doom_loop Срабатывает, когда один и тот же инструмент вызывается 3 раза подряд с одними и теми же входными данными (предотвращает застревание ИИ в цикле) — ask

Описание разрешения по умолчанию

Если вы не настроили никаких разрешений, OpenCode использует следующие встроенные значения по умолчанию:

  • Большинство разрешений инструментов по умолчанию"allow", что означает, что они выполняются автоматически без запроса
  • doom_loopиexternal_directoryПо умолчанию"ask", требующее ручного подтверждения
  • readЧтение всех файлов разрешено по умолчанию, но.envсвязанные файлы имеют встроенную защиту:

Пример

// Встроенные правила чтения OpenCode по умолчанию (ручная настройка не требуется, только для справки)
{
  "permission": {
    "read": {
"*": "allow", // Разрешить чтение всех файлов по умолчанию
"*.env": "deny", // Запретить чтение .env файлов (предотвратить утечку паролей к базе данных, API-ключей и т. д.)
"*.env.*": "deny", // Запретить чтение вариантов, таких как .env.local, .env.production
"*.env.example": "allow" // Разрешить чтение .env.example (пример файла, без реальных секретов)
    }
  }
}

Три варианта в запросе на подтверждение

Когда разрешение операции —"ask", OpenCode показывает запрос на подтверждение со следующими тремя вариантами:

Опция Эффект Сценарий применения
один раз (только в этот раз) Одобрить только этот запрос; при следующей такой же операции запрос всё равно появится Временно разрешить операцию, не включая её навсегда
всегда (всегда разрешать) Добавить шаблон сопоставления операции в белый список; больше не будет запросов до конца текущего сеанса Подтвердить, что определённый тип операции безопасен, и хотите, чтобы она автоматически пропускалась в этом сеансе
отклонить (отказаться) Отклонить этот запрос; операция не будет выполнена Операция кажется рискованной, и вы явно не хотите, чтобы она была выполнена

После выборавсегда, OpenCode заставит инструмент автоматически предложить шаблон белого списка (например, после одобренияgit status, обычно он добавитgit status*в белый список).Белый список действителен только для текущего сеанса и будет сброшен после перезапуска OpenCode.

Настройте разрешения отдельно для агентов

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

1. Настройте разрешения агента в opencode.json

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
// Глобальные разрешения: операции git разрешены, но commit и push запрещены
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
"build": { // Агент с именем build
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
"git commit *": "ask", // Переопределяет глобальные настройки: агент build разрешает commit, но требует подтверждения
"git push *": "deny", // Наследует глобальные настройки: push по-прежнему запрещён
          "grep *": "allow"
        }
      }
    }
  }
}

2. Настройте разрешения агента в файлах Markdown

Агенты также могут быть настроены через файлы Markdown, с разрешениями, записанными в YAML Front Matter в верхней части файла (---часть между ними):

Пример

# Путь к файлу: ~/.config/opencode/agents/review.md
---
description: Агент проверки кода (только анализирует код, не вносит изменений)
mode: subagent
permission:
  edit: deny        # Запретить любое редактирование файлов
  bash: ask         # команды bash требуют подтверждения
  webfetch: deny    # Запретить доступ к внешним URL
---

Только анализировать код и предлагать изменения.
# Ниже приведён системный промпт агента, описывающий обязанности агента и нормы поведения

Практические примеры конфигурации

Пример 1: Консервативный режим (все операции требуют подтверждения)

Подходит для новичков в OpenCode или при работе над важными проектами; все операции требуют ручного подтверждения:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask" // Все операции всех инструментов вызывают запросы на подтверждение
  }
}

Пример 2: Обычная конфигурация для разработки (операции чтения разрешены, операции записи требуют подтверждения)

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

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
"*": "ask", // Резервный вариант: инструменты, не настроенные отдельно, по умолчанию требуют подтверждения
"read": "allow", // Чтение файлов: разрешить напрямую
"glob": "allow", // Поиск файлов по glob: разрешить напрямую
"grep": "allow", // Поиск по содержимому: разрешить напрямую
"list": "allow", // Список каталогов: разрешить напрямую
    "bash": {
"*": "ask", // bash-команды по умолчанию требуют одобрения
"git status *": "allow", // Просмотр git status: разрешить
"git log *": "allow", // Просмотр git log: разрешить
"git diff *": "allow", // Просмотр git diff: разрешить
"npm run *": "allow", // Запуск npm-скриптов: разрешить
"npm test *": "allow", // Запуск тестов: разрешить
"rm *": "deny" // Удаление файлов: блокировать напрямую
    }
  }
}

Пример 3: Разрешить доступ к нескольким каталогам проектов

Когда ИИ нужно работать с несколькими каталогами проектов, предоставьте доступ к внешним каталогам:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
"~/projects/personal/**": "allow", // Разрешить доступ к каталогам личных проектов
"~/projects/work/**": "allow", // Разрешить доступ к рабочим каталогам проектов
"~/dotfiles/**": "allow" // Разрешить доступ к каталогу dotfiles
    },
    "edit": {
"~/dotfiles/**": "deny" // Даже если доступ к dotfiles разрешён, редактирование запрещено (только чтение)
    }
  }
}
Другие расширения