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

Чему вы научитесь

Настройка модели и параметров для каждого агента
Точный контроль разрешений агентов (редактирование файлов, выполнение Bash, веб-запросы и т.д.)
Добавление дополнительных инструкций через prompt_append
Создание пользовательских Category для динамических комбинаций агентов
Включение/отключение конкретных агентов, Skill, Hook и MCP

Ваша текущая проблема

Конфигурация по умолчанию работает хорошо, но не полностью соответствует вашим потребностям:

Oracle использует GPT 5.2, который слишком дорогой, вы хотите использовать более дешёвую модель
Агент Explore не должен иметь прав на запись файлов, только поиск
Librarian должен приоритетно искать официальную документацию, а не GitHub
определённый Hook выдаёт ложные срабатывания, вы хотите временно его отключить

Вам нужна "глубокая настройка" — не "просто работает", а "точно нужно".

🎒 Подготовка

Требования

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

Что вам нужно знать:

Расположение файла конфигурации: ~/.config/opencode/oh-my-opencode.json (уровень пользователя) или .opencode/oh-my-opencode.json (уровень проекта)
Конфигурация уровня пользователя имеет приоритет над конфигурацией уровня проекта

Основная концепция

Приоритет конфигурации: конфигурация уровня пользователя > конфигурация уровня проекта > конфигурация по умолчанию

~/.config/opencode/oh-my-opencode.json (высший приоритет)
    ↓ переопределяет
.opencode/oh-my-opencode.json (уровень проекта)
    ↓ переопределяет
oh-my-opencode встроенные значения по умолчанию (низший приоритет)

Файл конфигурации поддерживает JSONC:

Можно добавлять комментарии с помощью //
Можно добавлять блочные комментарии с помощью /* */
Можно использовать завершающие запятые

Следуйте за мной

Шаг 1: Найдите файл конфигурации и включите автодополнение Schema

Почему После включения JSON Schema редактор автоматически покажет все доступные поля и типы, предотвращая ошибки в конфигурации.

Действия:

jsonc

{
  // Добавьте эту строку для включения автодополнения
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  
  // Ваша конфигурация...
}

Что вы должны увидеть:

В VS Code / JetBrains и других редакторах после ввода { автоматически появятся все доступные поля
При наведении курсора на поле будет показано описание и тип

Шаг 2: Настройка модели агента

Почему Разные задачи требуют разных моделей:

Архитектурный дизайн: используйте самую мощную модель (Claude Opus 4.5)
Быстрое исследование: используйте самую быструю модель (Grok Code)
UI дизайн: используйте визуальную модель (Gemini 3 Pro)
Контроль затрат: для простых задач используйте недорогие модели

Действия:

jsonc

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  "agents": {
    // Oracle: стратегический консультант, использует GPT 5.2
    "oracle": {
      "model": "openai/gpt-5.2",
      "temperature": 0.1  // Низкая температура, более детерминированная
    },

    // Explore: быстрое исследование, использует бесплатную модель
    "explore": {
      "model": "opencode/gpt-5-nano",  // Бесплатная
      "temperature": 0.3
    },

    // Librarian: поиск документации, использует модель с большим контекстом
    "librarian": {
      "model": "anthropic/claude-sonnet-4-5"
    },

    // Multimodal Looker: анализ медиа, использует Gemini
    "multimodal-looker": {
      "model": "google/gemini-3-flash"
    }
  }
}

Что вы должны увидеть:

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

Шаг 3: Настройка разрешений агента

Почему Некоторые агенты не должны иметь все разрешения:

Oracle (стратегический консультант): только чтение, не нужна запись файлов
Librarian (эксперт по исследованиям): только чтение, не нужно выполнять Bash
Explore (исследование): только чтение, не нужны веб-запросы

Действия:

jsonc

{
  "agents": {
    "explore": {
      // Запретить запись файлов и выполнение Bash, разрешить только веб-поиск
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "webfetch": "allow"
      }
    },

    "librarian": {
      // Только права на чтение
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "webfetch": "allow"  // Нужно для поиска документации
      }
    },

    "oracle": {
      // Только права на чтение
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "webfetch": "allow"  // Нужно для поиска информации
      }
    },

    // Sisyphus: главный оркестратор, может выполнять все операции
    "sisyphus": {
      "permission": {
        "edit": "allow",
        "bash": "allow",
        "webfetch": "allow"
      }
    }
  }
}

Описание разрешений:

Разрешение	Значение	Описание
`edit`	`ask/allow/deny`	Разрешение на редактирование файлов
`bash`	`ask/allow/deny` или объект	Разрешение на выполнение Bash (можно детализировать для конкретных команд)
`webfetch`	`ask/allow/deny`	Разрешение на веб-запросы
`doom_loop`	`ask/allow/deny`	Позволяет агенту переопределять обнаружение бесконечного цикла
`external_directory`	`ask/allow/deny`	Разрешение на доступ к каталогам вне проекта

Детализация разрешений Bash:

jsonc

{
  "agents": {
    "explore": {
      "permission": {
        "bash": {
          "git": "allow",      // Разрешить выполнение git команд
          "grep": "allow",     // Разрешить выполнение grep
          "rm": "deny",       // Запретить удаление файлов
          "mv": "deny"        // Запретить перемещение файлов
        }
      }
    }
  }
}

Что вы должны увидеть:

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

Шаг 4: Использование prompt_append для добавления дополнительных инструкций

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

Заставить Librarian приоритетно искать определённую документацию
Заставить Oracle следовать определённым паттернам архитектуры
Заставить Explore использовать определённые ключевые слова поиска

Действия:

jsonc

{
  "agents": {
    "librarian": {
      // Добавляется после системного промпта по умолчанию, не заменяет его
      "prompt_append": "Always use elisp-dev-mcp for Emacs Lisp documentation lookups. " +
                      "When searching for docs, prioritize official documentation over blog posts."
    },

    "oracle": {
      "prompt_append": "Follow SOLID principles and Clean Architecture patterns. " +
                    "Always suggest TypeScript types for all function signatures."
    },

    "explore": {
      "prompt_append": "When searching code, prioritize recent commits and actively maintained files. " +
                    "Ignore test files unless explicitly asked."
    }
  }
}

Что вы должны увидеть:

Поведение агента изменяется, но сохраняются его исходные возможности
Например, Oracle всегда будет предлагать типы TypeScript при ответах

Шаг 5: Настройка пользовательских Category

Почему Category — это новая функция v3.0, реализующая динамические комбинации агентов:

Предустановка модели и параметров для определённых типов задач
Быстрый вызов через delegate_task(category="...")
Более эффективно, чем "вручную выбрать модель + написать промпт"

Действия:

jsonc

{
  "categories": {
    // Пользовательский: задачи по науке о данных
    "data-science": {
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.2,
      "prompt_append": "Focus on data analysis, ML pipelines, and statistical methods. " +
                     "Use pandas/numpy for Python and dplyr/tidyr for R."
    },

    // Переопределение по умолчанию: UI задачи используют пользовательский промпт
    "visual-engineering": {
      "model": "google/gemini-3-pro",
      "prompt_append": "Use shadcn/ui components and Tailwind CSS. " +
                     "Ensure responsive design and accessibility."
    },

    // Переопределение по умолчанию: быстрые задачи
    "quick": {
      "model": "anthropic/claude-haiku-4-5",
      "temperature": 0.1,
      "prompt_append": "Be concise. Focus on simple fixes and quick searches."
    }
  }
}

Поля конфигурации Category:

Поле	Описание	Пример
`model`	Используемая модель	`"anthropic/claude-sonnet-4-5"`
`temperature`	Температура (0-2)	`0.2` (детерминированность) / `0.8` (творчество)
`top_p`	Ядерная выборка (0-1)	`0.9`
`maxTokens`	Максимальное количество токенов	`4000`
`thinking`	Конфигурация Thinking	`{"type": "enabled", "budgetTokens": 16000}`
`prompt_append`	Дополнительный промпт	`"Use X for Y"`
`tools`	Разрешения на инструменты	`{"bash": false}`
`is_unstable_agent`	Пометка как нестабильный (принудительный фоновый режим)	`true`

Использование Category:

// В OpenCode
delegate_task(category="data-science", prompt="Проанализируйте этот набор данных и создайте визуализацию")
delegate_task(category="visual-engineering", prompt="Создайте адаптивный компонент панели управления")
delegate_task(category="quick", prompt="Найдите определение этой функции")

Что вы должны увидеть:

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

Шаг 6: Отключение определённых функций

Почему Некоторые функции могут не подходить для вашего рабочего процесса:

comment-checker: ваш проект позволяет подробные комментарии
agent-usage-reminder: вы знаете, какой агент использовать когда
определённый MCP: вам он не нужен

Действия:

jsonc

{
  // Отключение определённых Hooks
  "disabled_hooks": [
    "comment-checker",           // Не проверять комментарии
    "agent-usage-reminder",       // Не предлагать рекомендации по использованию агентов
    "startup-toast"               // Не показывать уведомление при запуске
  ],

  // Отключение определённых Skills
  "disabled_skills": [
    "playwright",                // Не использовать Playwright
    "frontend-ui-ux"            // Не использовать встроенный Skill для фронтенда
  ],

  // Отключение определённых MCPs
  "disabled_mcps": [
    "websearch",                // Не использовать поиск Exa
    "context7",                // Не использовать Context7
    "grep_app"                 // Не использовать grep.app
  ],

  // Отключение определённых агентов
  "disabled_agents": [
    "multimodal-looker",        // Не использовать мультимодальный Looker
    "metis"                   // Не использовать предварительное планирование Metis
  ]
}

Список доступных Hooks (частично):

Название Hook	Функция
`todo-continuation-enforcer`	Принудительное завершение списка TODO
`comment-checker`	Обнаружение избыточных комментариев
`tool-output-truncator`	Обрезка вывода инструментов для экономии контекста
`keyword-detector`	Обнаружение ключевых слов, таких как ultrawork
`agent-usage-reminder`	Предложение, какой агент использовать
`session-notification`	Уведомление о завершении сеанса
`background-notification`	Уведомление о завершении фоновой задачи

Что вы должны увидеть:

Отключённые функции больше не выполняются
После повторного включения функциональность восстанавливается

Шаг 7: Настройка управления параллелизмом фоновых задач

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

Избегание ограничения скорости API
Контроль затрат (дорогие модели не могут быть слишком параллельными)
Соблюдение квот провайдера

Действия:

jsonc

{
  "background_task": {
    // Максимальное количество одновременных операций по умолчанию
    "defaultConcurrency": 5,

    // Ограничения параллелизма на уровне провайдера
    "providerConcurrency": {
      "anthropic": 3,      // Максимум 3 одновременных запроса к Anthropic API
      "openai": 5,         // Максимум 5 одновременных запросов к OpenAI API
      "google": 10          // Максимум 10 одновременных запросов к Gemini API
    },

    // Ограничения параллелизма на уровне модели (высший приоритет)
    "modelConcurrency": {
      "anthropic/claude-opus-4-5": 2,     // Opus слишком дорогой, ограничить до 2 одновременных
      "google/gemini-3-flash": 10,          // Flash дешёвый, разрешить 10 одновременных
      "anthropic/claude-haiku-4-5": 15      // Haiku ещё дешевле, разрешить 15 одновременных
    }
  }
}

Порядок приоритетов:

modelConcurrency > providerConcurrency > defaultConcurrency

Что вы должны видеть:

Фоновые задачи, превышающие лимит параллелизма, ставятся в очередь ожидания
Параллелизм дорогих моделей ограничен, экономя затраты

Шаг 8: Включение экспериментальных функций

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

aggressive_truncation: более агрессивная обрезка контекста
auto_resume: автоматическое восстановление после сбоев
truncate_all_tool_outputs: обрезка всех выводов инструментов

Предупреждение

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

Действия:

jsonc

{
  "experimental": {
    // Включение более агрессивной обрезки вывода инструментов
    "aggressive_truncation": true,

    // Автоматическое восстановление после ошибок thinking block
    "auto_resume": true,

    // Обрезка всех выводов инструментов (не только Grep/Glob/LSP/AST-Grep)
    "truncate_all_tool_outputs": false
  }
}

Что вы должны увидеть:

В агрессивном режиме вывод инструментов более строго обрезается для экономии контекста
После включения auto_resume агент автоматически восстановится и продолжит работу при ошибках

Контрольная точка ✅

Проверка применения конфигурации:

bash

# Запуск диагностической команды
bunx oh-my-opencode doctor --verbose

Что вы должны увидеть:

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

Предупреждения о возможных проблемах

1. Ошибки в формате файла конфигурации

Проблема:

Ошибки синтаксиса JSON (отсутствие или лишние запятые)
Ошибки в написании имён полей (temperature написано как temparature)

Решение:

bash

# Проверка формата JSON
cat ~/.config/opencode/oh-my-opencode.json | jq .

2. Слишком строгая конфигурация разрешений

Проблема:

Некоторые агенты полностью отключены (edit: "deny", bash: "deny")
Агент не может выполнять обычную работу

Решение:

Агенты только для чтения (Oracle, Librarian) могут отключать edit и bash
Главный оркестратор (Sisyphus) нуждается в полных разрешениях

3. Конфигурация Category не применяется

Проблема:

Ошибка в написании названия Category (visual-engineering написано как visual-engineering)
delegate_task не указывает параметр category

Решение:

Проверьте, совпадает ли название в delegate_task(category="...") с конфигурацией
Используйте doctor --verbose для проверки результатов разбора Category

4. Слишком низкое ограничение параллелизма

Проблема:

modelConcurrency слишком низкий (например, 1)
Фоновые задачи выполняются почти последовательно, теряя преимущество параллелизма

Решение:

Установите разумное значение в соответствии с бюджетом и квотами API
Дорогие модели (Opus) ограничьте до 2-3, дешёвые (Haiku) могут быть 10+

Итоги урока

Глубокая настройка конфигурации = точный контроль:

Параметр конфигурации	Назначение	Распространённые сценарии
`agents.model`	Переопределение модели агента	Оптимизация затрат, адаптация к задачам
`agents.permission`	Контроль разрешений агента	Безопасность, режим только для чтения
`agents.prompt_append`	Добавление дополнительных инструкций	Соблюдение архитектурных стандартов, оптимизация стратегии поиска
`categories`	Динамические комбинации агентов	Быстрый вызов определённых типов задач
`background_task`	Контроль параллелизма	Контроль затрат, квоты API
`disabled_*`	Отключение определённых функций	Удаление неиспользуемых функций

Запомните:

Конфигурация уровня пользователя (~/.config/opencode/oh-my-opencode.json) имеет приоритет над уровнем проекта
Используйте JSONC для более читаемой конфигурации
Запустите oh-my-opencode doctor --verbose для проверки конфигурации

Предпросмотр следующего урока

Следующий урок: Диагностика и устранение неполадок конфигурации.
Вы узнаете:
Использование команды doctor для проверки работоспособности
Диагностика проблем с версиями OpenCode, регистрацией плагинов, настройкой провайдера и т.д.
Понимание механизма разбора моделей и конфигурации Categories
Использование вывода JSON для автоматизированной диагностики

Приложение: исходный код

Нажмите, чтобы раскрыть расположение исходного кода

Обновлено: 2026-01-26

Функция	Путь к файлу	Строки
Определение Schema конфигурации	`src/config/schema.ts`	1-378
AgentOverrideConfig	`src/config/schema.ts`	98-119
CategoryConfig	`src/config/schema.ts`	154-172
AgentPermissionSchema	`src/config/schema.ts`	11-17
OhMyOpenCodeConfigSchema	`src/config/schema.ts`	329-350
Документация конфигурации	`docs/configurations.md`	1-595

Ключевые константы:

PermissionValue = z.enum(["ask", "allow", "deny"]): перечисление значений разрешений

Ключевые типы:

AgentOverrideConfig: конфигурация переопределения агента (модель, температура, промпт и т.д.)
CategoryConfig: конфигурация Category (модель, температура, промпт и т.д.)
AgentPermissionSchema: конфигурация разрешений агента (edit, bash, webfetch и т.д.)
BackgroundTaskConfig: конфигурация параллелизма фоновых задач

Перечисление встроенных агентов (BuiltinAgentNameSchema):

sisyphus, prometheus, oracle, librarian, explore, multimodal-looker, metis, momus, atlas

Перечисление встроенных Skill (BuiltinSkillNameSchema):

playwright, agent-browser, frontend-ui-ux, git-master

Перечисление встроенных Category (BuiltinCategoryNameSchema):

visual-engineering, ultrabrain, artistry, quick, unspecified-low, unspecified-high, writing

Глубокая настройка конфигурации: управление агентами и разрешениями ​

Чему вы научитесь ​

Ваша текущая проблема ​

🎒 Подготовка ​

Основная концепция ​

Следуйте за мной ​

Шаг 1: Найдите файл конфигурации и включите автодополнение Schema ​

Шаг 2: Настройка модели агента ​

Шаг 3: Настройка разрешений агента ​

Шаг 4: Использование prompt_append для добавления дополнительных инструкций ​

Шаг 5: Настройка пользовательских Category ​

Шаг 6: Отключение определённых функций ​

Шаг 7: Настройка управления параллелизмом фоновых задач ​

Шаг 8: Включение экспериментальных функций ​

Контрольная точка ✅ ​

Предупреждения о возможных проблемах ​

1. Ошибки в формате файла конфигурации ​

2. Слишком строгая конфигурация разрешений ​

3. Конфигурация Category не применяется ​

4. Слишком низкое ограничение параллелизма ​

Итоги урока ​

Предпросмотр следующего урока ​

Приложение: исходный код ​

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

Чему вы научитесь

Ваша текущая проблема

🎒 Подготовка

Основная концепция

Следуйте за мной

Шаг 1: Найдите файл конфигурации и включите автодополнение Schema

Шаг 2: Настройка модели агента

Шаг 3: Настройка разрешений агента

Шаг 4: Использование prompt_append для добавления дополнительных инструкций

Шаг 5: Настройка пользовательских Category

Шаг 6: Отключение определённых функций

Шаг 7: Настройка управления параллелизмом фоновых задач

Шаг 8: Включение экспериментальных функций

Контрольная точка ✅

Предупреждения о возможных проблемах

1. Ошибки в формате файла конфигурации

2. Слишком строгая конфигурация разрешений

3. Конфигурация Category не применяется

4. Слишком низкое ограничение параллелизма

Итоги урока

Предпросмотр следующего урока

Приложение: исходный код