2026-05-15 OpenClaw: AGENTS.md рабочей области как инструкция к репозиторию на безголовом арендованном облачном Mac Apple Silicon (HK / JP / KR / SG / US)

Когда OpenClaw может прочитать весь монорепозиторий, документ с наибольшим рычагом — не очередной параметр JSON, а дисциплинированный AGENTS.md в корне Git, который объясняет людям и моделям, что считается нормой. На арендованных Mac mini M4 в Гонконге, Токио, Сеуле, Сингапуре и США один и тот же хост часто совмещает xcodebuild, деревья подписи и ассистента, правящего Swift. В этом материале от 2026-05-15 AGENTS.md помещён в полный стек политик: он согласуется с корнями рабочей области, белыми списками и ограждениями монорепо, дополняет мультиагентное разделение ролей в agents.json и развивается вместе с onboard, launchd и разбором doctor — без построчного копирования машиночитаемых таблиц инструментов в Markdown.

Зачем нужен AGENTS.md уровня репозитория, если уже есть agents.json

agents.json кодирует личности, модели и поверхность инструментов; это контракт, который шлюз должен разбирать детерминированно. AGENTS.md отвечает на другие вопросы: какой продукт собирает репозиторий, какие каталоги трогать нельзя, какая тестовая команда является эталоном, как поэтапно откатываться и кого будить при рискованных правках. На общих арендованных билдерах такой текст показывает намерение в diff инцидента сильнее, чем одни массивы JSON. Держите объём так, чтобы вслух уложиться примерно в две минуты; длинные сценарии переносите в навыки, а здесь укажите путь входа и условия срабатывания.

Стек политик: место AGENTS.md относительно белых списков и agents.json

Сверху вниз: транспорт и каналы, маршрутизация шлюза, белые списки рабочей области, JSON среды выполнения агента, опциональные навыки и, наконец, описание репозитория. AGENTS.md ближе всего к «социальному контракту» репозитория — он не отменяет политику файловой системы по умолчанию «запрет, кроме разрешённого», но объясняет, зачем существуют корни и какое поведение ассистента там ожидается. Несколько агентов на одном хосте читают один и тот же репозиторий, поэтому AGENTS.md остаётся нейтральным к персонам, а сужение инструментов остаётся в agents.json.

Слой	Основной артефакт	Владелец	AGENTS.md должен…
Ограждение ФС	Белые списки рабочей области	Платформа / безопасность	Ссылаться на корни по путям, не вводить параллельные правила
Политика рантайма	agents.json	Владельцы автоматизации	Пояснять намерение профилей и давать ссылки на JSON в Git
Глубина процедур	Навыки / runbook	Сервисные команды	Индексировать стабильными заголовками, не вставлять многостраничный shell
Контекст человек+модель	AGENTS.md	Maintainers репозитория	Формулировать миссию, тесты, откат и контакты нейтральным тоном

Рекомендуемый каркас AGENTS.md для репозиториев с сильной зависимостью от OpenClaw

Используйте устойчивые заголовки, чтобы и люди, и модели могли быстро искать. Начните с абзаца о миссии, затем явно перечислите не-цели — действия, требующие человеческого одобрения (продакшен-релизы, запись в связку ключей, удаление DerivedData чужих веток). Зафиксируйте канонические точки входа для тестов (схемы xcodebuild test, выбор SwiftPM, обёртки линтеров) и переменные окружения, обязательные для неинтерактивных shell. Завершите эскалацией: канал мессенджера, дежурство, команда для снятия логов шлюза на арендованной машине.

• Миссия и охват — продуктовый контекст, ритм релизов, поддерживаемые ветки.
• Карта каталогов — сгенерированные артефакты, шаблоны секретов, расположение CI checkout.
• Проверка — минимальный набор команд, доказывающий безопасность изменения.
• Откат — стратегия отката в Git и очистка кэшей на хосте.

Бюджет токенов: AGENTS.md — тонкий слой, навыки — толстый

Большие куски Markdown конкурируют за контекст с фрагментами кода, которые подтягивают файловые инструменты. Предпочитайте короткие абзацы, таблицы ссылок и стабильные якоря. Длинные цепочки (тегирование релиза, notarize и stapling, мультирегиональный выкат) выносите в навыки, которые шлюз подгружает по необходимости. При ссылке на навык укажите относительный путь и триггер (например: «после полностью зелёного CI на main»). Раз в квартал пересматривайте объём: если больше примерно двух печатных страниц, разбивайте по ограниченному контексту (iOS-приложение против backend) и оставляйте индексный файл в корне.

Git-ревью, теги и дисциплина выкладки на хост

Поскольку AGENTS.md влияет на поведение модели, в pull request нужны ревьюеры и из предметной области, и из команды автоматизации. При существенных изменениях политики ставьте теги Git и дублируйте их в заметках к релизу, чтобы на арендованном хосте можно было сопоставить аномалии с известной версией документа. Избегайте правок только по SSH без немедленного коммита — расхождение рабочего дерева с origin/main часто объясняется тем, что ассистент следует старой версии текста. По возможности объединяйте правки agents.json и AGENTS.md в одном diff.

Реальности безголового арендованного Mac: shell, редакторы, симлинки

SSH-сессии часто используют bash или zsh с иным PATH, чем у графической среды. Зафиксируйте предположения о профиле в AGENTS.md и проверьте их теми же обёртками, что и launchd, прежде чем делегировать вызовы инструментов. Симлинки в монорепозитории могут создать впечатление выхода за пределы разрешённого корня — согласуйте формулировки с правилами разрешения из материалов о белых списках. Плагины автосохранения удалённых редакторов создают временные файлы — перечислите шаблоны игнорирования, чтобы они не читались как продуктовый код.

Матрица решений: править AGENTS.md, agents.json или добавлять новый навык

Сигнал	Скорее AGENTS.md	Скорее agents.json	Скорее новый навык
Изменение носит повествовательный или учебный характер	Да — миссия, предупреждения, ссылки	Нет — не набивайте JSON прозой	Только если процедура длинная
Меняются списки разрешённых/запрещённых инструментов	Сначала мотив в примечании, затем JSON	Да — машинное принуждение	Вспомогательный текст можно держать в навыке
Добавляется многошаговая shell-оркестрация	Короткая ссылка на путь навыка	Редко — JSON остаётся декларативным	Да — сохраняйте читаемость AGENTS.md
Срочный хотфикс	Обновите документ после инцидента	Сначала флаги возможностей или переключение маршрутизатора	Якоря постмортема — сюда

Девять шагов для внедрения AGENTS.md на арендованном билдере

1. Сверьте разрешённые корни с материалом о рабочей области от 2026-05-11; устраните расхождения до написания текста.
2. Подготовьте черновик AGENTS.md в feature-ветке; прогоните через iOS, backend и безопасность.
3. Сопоставьте каждый профиль agents.json с обязательными разделами; удалите дублирующие таблицы инструментов из основного текста.
4. Любую процедуру длиннее двенадцати шагов вынесите в навык со стабильной относительной ссылкой.
5. Локально прогоните проверки с той же мажорной версией Node, что и в продакшене (см. статью про onboard).
6. Слейте в main; поставьте тег policy/agents-md-ГГГГММДД для трассировки.
7. На арендованном хосте выполните pull и сверьте хеши с Git.
8. Перезапускайте шлюзы только при изменении JSON или переменных окружения; иначе следуйте семантике перечитывания файлов вашей сборки.
9. Зафиксируйте метрики до и после: отклонённые попытки вызова инструментов, средняя длина сессии, доля ручных переопределений.

Вопросы и ответы

Вопрос	Практический ответ (2026-05-15)
Стоит ли вносить API-ключи в AGENTS.md?	Нет — только имена хранилищ или ключи переменных окружения; значения держите в запечатанных файлах или связке ключей.
Можно ли поддерживать несколько языковых версий AGENTS.md?	Только если политика жёстко синхронизирована; иначе выберите один канонический язык, в остальных переводите ссылки, а не правила.
Как часто пересматривать AGENTS.md?	Как минимум раз в квартал и после крупных обновлений Xcode или OpenClaw; трактуйте документ как спутника дашбордов SLO.

Почему аренда Mac mini M4 упрощает итерации по AGENTS.md

Быстрый NVMe и unified memory дешёво удерживают несколько деревьев состояния агента, параллельные git checkout и крупные пакеты «Markdown + навыки», поэтому удобно репетировать правки документа на staging-аренде до продакшен-трафика. Сравните регионы на странице цены; перед расширением поверхности инструментов дайте команде прочитать руководства по SSH и опциональному VNC.