Настройка

Настройка позволяет адаптировать Codex к рабочим процессам вашей команды.

В Codex настройка состоит из нескольких взаимодополняющих уровней:

• Проектные инструкции (AGENTS.md) для постоянных указаний
• Память для полезного контекста, полученного в ходе предыдущей работы
• Навыки для многократно используемых рабочих процессов и экспертных знаний в предметной области
• MCP для доступа к внешним инструментам и общим системам
• Субагенты для делегирования работы специализированным субагентам

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

Инструкции AGENTS

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

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

• Команды сборки и тестирования
• Требования к проверке изменений
• Соглашения конкретного репозитория
• Инструкции для отдельных каталогов

Если агент делает неверные предположения о вашей кодовой базе, исправьте их в AGENTS.md и попросите агента обновить AGENTS.md, чтобы исправление сохранилось. Рассматривайте это как цикл обратной связи.

Когда следует обновлять AGENTS.md

• Повторяющиеся ошибки: если агент неоднократно совершает одну и ту же ошибку, добавьте соответствующее правило.
• Слишком много чтения: если агент находит нужные файлы, но читает слишком много документов, добавьте инструкции по навигации — укажите приоритетные каталоги и файлы.
• Повторяющиеся замечания к PR: если вы оставляете одно и то же замечание несколько раз, формализуйте его.
• В GitHub: в комментарии к pull request отметьте @codex и добавьте запрос (например, @codex add this to AGENTS.md), чтобы делегировать обновление облачному чату.
• Автоматизация проверок на расхождения: используйте запланированные задачи, чтобы регулярно (например, ежедневно) находить пробелы в инструкциях и предлагать дополнения для AGENTS.md.

Дополните AGENTS.md инфраструктурой, обеспечивающей соблюдение этих правил: хуки перед коммитом, линтеры и средства проверки типов выявляют проблемы до того, как их увидите вы, поэтому система всё эффективнее предотвращает повторяющиеся ошибки.

Codex может загружать инструкции из нескольких мест: из глобального файла в домашнем каталоге Codex (для вас как разработчика) и из файлов конкретного репозитория, которые команда может хранить в системе контроля версий. Файлы, расположенные ближе к рабочему каталогу, имеют приоритет. Используйте глобальный файл, чтобы настроить взаимодействие Codex с вами — например, стиль проверки, подробность ответов и значения по умолчанию, — а файлы репозитория посвятите правилам команды и кодовой базы.

<FileTree class="mt-4" tree={[ { name: "~/.codex/", open: true, children: [ { name: "AGENTS.md", comment: "Глобальный (для вас как разработчика)" }, ], }, { name: "repo-root/", open: true, children: [ { name: "AGENTS.md", comment: "Для конкретного репозитория (для вашей команды)" }, ], }, ]} />

Пользовательские инструкции с AGENTS.md

Навыки

Навыки предоставляют Codex многократно используемые возможности для повторяемых рабочих процессов. Навыки часто лучше всего подходят для таких процессов, поскольку позволяют использовать более подробные инструкции, скрипты и справочные материалы, сохраняя возможность повторного применения в разных задачах. Навыки загружаются и доступны агенту — как минимум их метаданные, — поэтому Codex может находить и выбирать их автоматически. Благодаря этому сложные рабочие процессы остаются доступными, не перегружая контекст заранее.

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

Обычно навык состоит из файла SKILL.md и необязательных скриптов, справочных материалов и ресурсов.

<FileTree class="mt-4" tree={[ { name: "my-skill/", open: true, children: [ { name: "SKILL.md", comment: "Обязательно: инструкции и метаданные" }, { name: "scripts/", comment: "Необязательно: исполняемый код" }, { name: "references/", comment: "Необязательно: документация" }, { name: "assets/", comment: "Необязательно: шаблоны и ресурсы" }, ], }, ]} />

Каталог навыка может содержать папку scripts/ со скриптами CLI, которые Codex запускает в рамках рабочего процесса — например, для заполнения тестовыми данными или выполнения проверок. Если рабочему процессу требуется доступ к внешним системам — трекерам задач, инструментам проектирования или серверам документации, — объедините навык с MCP.

Пример SKILL.md:

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

Используйте навыки для:

• Повторяемых рабочих процессов (этапы выпуска, процедуры проверки, обновление документации)
• Экспертных знаний конкретной команды
• Процедур, которым нужны примеры, справочные материалы или вспомогательные скрипты

Навыки могут быть глобальными (в вашем пользовательском каталоге, для вас как разработчика) или относиться к конкретному репозиторию (храниться в .agents/skills, для вашей команды). Размещайте навыки репозитория в .agents/skills, если рабочий процесс относится к этому проекту; пользовательский каталог используйте для навыков, которые нужны вам во всех репозиториях.

Codex использует поэтапное раскрытие информации о навыках:

• Сначала для обнаружения используются метаданные (name, description)
• SKILL.md загружается только после выбора навыка
• Справочные материалы читаются, а скрипты запускаются только при необходимости

Навыки можно вызывать явно; кроме того, Codex может выбрать их автоматически, если задача соответствует описанию навыка. Чёткие описания навыков повышают надёжность их активации.

Создание навыков

MCP

MCP (Model Context Protocol) — стандартный способ подключения Codex к внешним инструментам и поставщикам контекста. Он особенно полезен для удалённых систем, таких как Figma, Linear, GitHub или внутренние информационные сервисы, от которых зависит ваша команда.

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

Один из способов представить эту архитектуру:

• Хост: Codex
• Клиент: соединение MCP внутри Codex
• Сервер: внешний инструмент или поставщик контекста

Серверы MCP могут предоставлять:

• Инструменты (действия)
• Ресурсы (данные для чтения)
• Промпты (многократно используемые шаблоны промптов)

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

На практике MCP часто наиболее полезен в сочетании с навыками:

• Навык определяет рабочий процесс и указывает, какие инструменты MCP следует использовать

Model Context Protocol

Субагенты

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

Субагенты

Совместное использование навыков и MCP

Сочетание навыков и MCP объединяет все возможности: навыки определяют повторяемые рабочие процессы, а MCP подключает их к внешним инструментам и системам. Если навык зависит от MCP, объявите эту зависимость в agents/openai.yaml, чтобы Codex мог автоматически установить и настроить её (см. Создание навыков).

Следующий шаг

Выполняйте настройку в следующем порядке:

1. Добавьте пользовательские инструкции с AGENTS.md, чтобы Codex следовал соглашениям вашего репозитория. Настройте хуки перед коммитом и линтеры для обеспечения соблюдения этих правил.
2. Установите плагин, если подходящий многократно используемый рабочий процесс уже существует. В противном случае создайте навык и оформите его как плагин, когда захотите поделиться им.
3. Настройте MCP, если рабочим процессам нужен доступ к внешним системам (Linear, GitHub, серверам документации или инструментам проектирования).
4. Используйте субагентов, когда будете готовы делегировать им задачи с большим объёмом вспомогательной работы или задачи, требующие узкой специализации.