Конфигурация¶

Файл конфигурации — закрытый список значений, которые эта установка должна соблюдать. Секреты, токены и облачные учётные данные здесь не живут: они живут в секретном хранилище операционной системы.

Каждую команду на этой странице копируйте с --json. config show — чтение. config init, config set и config unset — apply. Ни одна из них не destructive.

Повседневная первая запись catalogued instruction surface — intent initialize. config init ниже — expert recovery.

ai-stp task start --intent initialize --idempotency-key initialize-session-01 --json

Команды¶

Команда	Mutability	Confirmation	Когда
config init	`apply`	`none`	создать файл конфигурации, если его нет, и в любом случае провалидировать
`ai-stp config set`	`apply`	`none`	записать заявленные значения в файл конфигурации
`ai-stp config unset`	`apply`	`none`	убрать заявленные значения, чтобы снова действовали значения по умолчанию
`ai-stp config validate`	`read`	`none`	прочитать файл конфигурации и отказать, если его нельзя соблюсти
`ai-stp config show`	`read`	`none`	показать действующую конфигурацию и откуда взялось каждое значение

Список полей закрыт. Неизвестный ключ — типизированная ошибка с путём, а не молчаливый пропуск. Запись telemetry.enabled=true в файл отклоняется: телеметрию включает только согласие Телеметрия установки.

Типичный путь¶

ai-stp task start --intent initialize --idempotency-key initialize-session-01 --json

Expert recovery (config init идемпотентен: если файл уже есть, команда проверяет его, а не заменяет):

ai-stp config init --json
ai-stp config show --json
ai-stp config validate --json

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

ai-stp config set --set search.result_limit=10 --json
ai-stp config show --json

Чтобы вернуть поле к значению по умолчанию:

ai-stp config unset --field search.result_limit --json
ai-stp config show --json

--set и --field — объявленные опции. Их можно повторять для нескольких путей. Форма присваивания — path=value. Путь без = отклоняется, а не считается молчаливым no-op.

Объявленные поля¶

Это пути, которые понимает этот билд. Точные имена, типы и значения по умолчанию — в ai-stp help --agent --json и в config show.

Путь	Чем управляет
`catalog.enabled`	обращаться ли к публичному каталогу
`catalog.url`	базовый адрес платформы без префикса `/v1`
`sync.enabled`	включена ли облачная синхронизация; нужен вход
`registry.path`	где живёт локальный реестр
`search.result_limit`	верхняя граница кандидатов в результате
`projects.discovery_roots`	явные корни, в которых ищут проекты
`telemetry.enabled`	отправляется ли анонимный ping установки
`telemetry.url`	куда этот ping ушёл бы
`provider.paths.<harness>`	абсолютный путь к setup-system provider этого harness

<harness> — одно из antigravity, claude-code, codex, cursor, grok-build, opencode, pi. Неизвестный harness — не поле.

source у каждого значения — одно из default, config_file или command_argument. «20, потому что так по умолчанию» и «20, потому что вы написали 20» ведут к разным следующим шагам. Поэтому config show сообщает и значение, и источник.

config show --set — это не запись

config show принимает переопределение только для этого вызова в виде path=value. Файл он не пишет. Запись — config set. Не путайте одно с другим.

`config init`¶

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

ai-stp config init --json

Никогда не перезаписывает. Запуск против существующего файла проверяет этот файл — именно это спрашивает вызывающий, которому нужно знать, что файлом можно пользоваться.

`config set`¶

Записать заявленные значения в файл конфигурации.

ai-stp config set --set search.result_limit=10 --json

Ответ — действующая конфигурация после записи, поэтому видно и новое значение, и то, что его source теперь config_file. Неизвестный путь, значение, которое поле не может держать, или ключ в форме секрета отклоняются.

Телеметрию так включить нельзя:

ai-stp config set --set telemetry.enabled=true --json

Этот вызов отклоняется с AI_STP_USER_DECISION_REQUIRED. Следующее действие — telemetry consent, а не ещё один config set.

`config unset`¶

Убрать заявленные значения, чтобы снова действовали значения по умолчанию.

ai-stp config unset --field search.result_limit --json

Снять поле, которое никогда не записывали, — успешный no-op для этого пути: значение по умолчанию уже действует. Снять ничего — отказ.

`config validate`¶

Прочитать файл конфигурации и отказать, если его нельзя соблюсти.

ai-stp config validate --json

То же чтение, что у config show, без вопроса «что переопределил бы этот вызов». Нужна, когда важно только, цел ли файл.

Файл с schema_version, на котором этот билд не говорит, отклоняется, а не читается оптимистично. Невалидный YAML отклоняется. Отображение с необъявленным ключом отклоняется, в том числе опечатка внутри объявленной секции.

`config show`¶

Показать действующую конфигурацию и откуда взялось каждое значение.

ai-stp config show --json

Это чтение. Если файла нет, каждое значение сообщается из default, а config_path всё равно называет, где файл жил бы.

Что содержит успешный конверт¶

Все пять команд возвращают одну форму в data:

Поле	Что это
`config_path`	где файл, или `null`, когда пути называть нечего
`values`	каждое объявленное поле с `path`, `source` и `value`
`schema_version`	major схемы этого отчёта

source — default, config_file или command_argument. Путевые значения в отчёте свёрнуты относительно домашнего каталога; это отображение, а не другой путь на диске.

Конверт также несёт ok, warnings, next_actions, request_id, operation_id и schema_version.

Чего эти команды никогда не делают¶

не хранят токен, пароль, ключ и учётные данные;
не включают телеметрию записью telemetry.enabled=true;
не создают устройство и паспорт;
не обращаются к каталогу, даже если catalog.enabled истинно — это Реестр;
не меняют target harness.

Типичные отказы¶

Что видно	Что это значит	Что делать
`AI_STP_VALIDATION_ERROR` «not valid YAML»	файл нельзя разобрать	исправить файл; не удалять его, чтобы повторить `init`
`AI_STP_VALIDATION_ERROR` unknown path	этого ключа нет в закрытом списке полей	`config show --json` и взять путь, который он называет
`AI_STP_VALIDATION_ERROR` «nothing was set»	`config set` без `path=value`	передать `--set path=value`
`AI_STP_VALIDATION_ERROR` «nothing was unset»	`config unset` без поля	передать `--field`
`AI_STP_USER_DECISION_REQUIRED` на `telemetry.enabled`	согласие — событие, а не значение файла	`ai-stp telemetry consent --accept --confirm --json` или `--decline`
`AI_STP_VALIDATION_ERROR` schema version	файл писал другой билд	не угадывать, какие ключи ещё значат то же

Связанные страницы¶

Страница	Зачем
Наблюдение	`doctor` сообщает проверку конфигурации
Телеметрия установки	единственный способ включить ping
Устройство	идентичность — не поле конфигурации
Вход	облачные учётные данные живут в секретном хранилище
Provider	`provider.paths.<harness>` называет бинарник
Проект	`projects.discovery_roots` — вход для discovery
Диагностика	PATH и сбои первого запуска

Флаги из ai-stp help --agent --json

Если help --agent расходится с флагом на этой странице, прав CLI. Необязательные флаги здесь не перечислены. Читайте их из дескриптора.