Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал

Неинтерактивный CLI (ax-code run)

Статус: действует Область: текущее состояние Последняя проверка: 2026-09-22 Владелец: сопровождающие среды выполнения AX Code

ax-code run — одноразовая неинтерактивная точка входа для агентов написания кода с ИИ и для сценариев. Команда отправляет один промпт, печатает итоговый ответ ассистента и завершается: без терминального интерфейса и без интерактивных запросов. Это руководство описывает набор параметров, контракт вывода, коды выхода и готовые рецепты для сценариев и CI.

Запуск прогона

Промпт можно передать четырьмя способами. Они складываются по порядку: --prompt-file, затем -p/--prompt, затем позиционное сообщение, затем stdin из канала.

# Positional after -- (safest; flags after -- are never consumed as options)
ax-code run --model qwen -- "Review this change"

# Explicit prompt flag
ax-code run --model qwen --prompt "Review this change"
ax-code run --model qwen -p "Review this change"

# Prompt read from a file (not an attachment)
ax-code run --model qwen --prompt-file ./prompt.txt

# Piped stdin (used as the prompt when no positional/--prompt is given)
printf 'Review this change' | ax-code run --model qwen

Если stdin не является TTY, его содержимое добавляется к собранному промпту и становится всем промптом, когда больше ничего не передано. Читатель stdin ждёт окно тишины 300 мс, прежде чем отказаться от открытого канала, поэтому записывайте промпт сразу и закрывайте stdin — либо используйте --prompt-file для больших или медленно поступающих промптов. --prompt-file - явно читает промпт из stdin (ошибка использования, если stdin — это TTY). Неявное добавление stdin из канала для этого вызова второй раз не выполняется.

-f/--file прикрепляет файлы к сообщению и никогда не заменяет промпт. Флаг повторяемый:

ax-code run --model qwen --file README.md --file src/main.ts -- "Summarize these"

Вложение должно находиться внутри каталога проекта: сервер отказывает во вложениях вне его независимо от правил прав, поэтому CLI отклоняет их заранее с ошибкой использования. Скопируйте файл в проект или передайте его содержимое через --prompt-file. --add-dir даёт инструментам доступ к дополнительным каталогам, но это правило не меняет.

Типы MIME вложений выводятся из расширения: png, jpg, jpeg, gif и webp сопоставляются своему типу image/*, а pdf — типу application/pdf, поэтому двоичные вложения доходят до сервера своим настоящим типом, а не как text/plain. Всё остальное, включая файл без распознанного расширения, отправляется как text/plain, а вложение-каталог классифицируется как application/x-directory.

Управление прогоном

Три флага направляют прогон, не меняя текст промпта. Все они только в длинной форме и в kebab-case.

--append-system-prompt TEXT / --append-system-prompt-file PATH

Добавляет дополнительный текст к системному промпту после системных промптов агента и окружения. Текст добавляется и никогда не заменяет встроенный системный промпт. Две формы взаимоисключающие. Вариант с файлом удобен для более длинных инструкций. Обрезается ровно один завершающий перевод строки, а пустой текст или нечитаемый файл — это ошибка использования до отправки чего-либо.

ax-code run --model qwen --append-system-prompt "Answer in English only" -- "Review this change"

--disallowed-tools a,b

Отключает инструменты по идентификатору на время прогона (через запятую, флаг повторяемый). Применяется через оба механизма сервера: правила запрета в созданном сеансе покрывают новые прогоны, а карта инструментов на запрос покрывает и возобновлённые прогоны --session/--continue. Запрет bash также запрещает команду инструмента monitor, которая идёт через тот же запускатель оболочки. Вызов, попавший в правило запрета, завершается ошибкой инструмента и считается отказом для статуса заблокированного прогона. Неизвестные идентификаторы не являются ошибкой: идентификаторы инструментов MCP динамические. Но в формате по умолчанию каждый идентификатор вне встроенного набора инструментов печатает одно предупреждение в stderr (его подавляет --quiet).

ax-code run --model qwen --disallowed-tools bash,write -- "Audit this module without mutating anything"

--add-dir PATH

Даёт агенту доступ к одному дополнительному каталогу (флаг повторяемый): в правила прав нового сеанса добавляется правило разрешения external_directory для <resolved-path>/*, покрывающее каталог и всё внутри него. Каждый путь должен существовать и быть каталогом (разрешается относительно текущего каталога вызывающей стороны, как --file). Правило применяется при создании сеанса, поэтому при --session/--continue оно не может подействовать: CLI печатает --add-dir applies only to new sessions в stderr и продолжает. Правило не меняет ограничение --file: вложения по-прежнему должны лежать внутри каталога проекта. Оно покрывает файловые инструменты (read, glob, grep, list, edit, write). Команда оболочки, которая заходит в каталог через динамический путь, всё равно вызывает промпт доступа к пути только для интерактивного режима, а неинтерактивный прогон отклоняет его автоматически. Поэтому предпочитайте файловые инструменты или передавайте содержимое файла явно.

ax-code run --model qwen --add-dir ../design-docs -- "Read ../design-docs/spec.md and summarize it"

Выбор модели

Список пригодных идентификаторов даёт ax-code models. Передайте полученное значение provider/model в --model (-m):

ax-code models            # one "provider/model" ID per line
ax-code models --json     # one JSON document

ax-code models --json печатает один документ вида {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]}.

Имена семейств deepseek, glm и qwen разрешаются в их значения Flash по умолчанию, поэтому ax-code run --model qwen -- "..." работает без полного идентификатора provider/model. Если опустить --model, используется настроенное значение по умолчанию. Действующие агент и модель печатаются в stderr как > Agent · model.

Форматы вывода

--format принимает default (значение по умолчанию), json, jsonl или ndjson (jsonl и ndjson — псевдонимы json).

По умолчанию (текст)

Формат по умолчанию печатает в stdout только итоговый текст ассистента. Весь ход работы, активность инструментов и диагностика идут в stderr, начиная с заголовка > Agent · model · ses_..., который включает идентификатор сеанса, чтобы вызывающий код с несколькими ходами мог возобновить работу через --session, не переключаясь на --format json (--quiet подавляет заголовок). Цвета ANSI отключаются, если stderr не является TTY или если задана NO_COLOR (любое значение), поэтому прогон в канале никогда не выдаёт escape-коды.

Поток JSON (--format json)

--format json печатает поток событий JSON с разделителем-переводом строки (NDJSON): один объект JSON на строку, а не один документ JSON. События включают step_start, text, tool_use, reasoning (только вместе с --thinking), permission_denied, error и step_finish. Поток всегда заканчивается ровно одной строкой result:

{
  "type": "result",
  "timestamp": 1727000000000,
  "sessionID": "ses_...",
  "status": "completed",
  "text": "...",
  "permissionDenials": 0,
  "usage": { "input": 1200, "output": 80, "reasoning": 0, "cacheRead": 0, "cacheWrite": 0 }
}

status равен completed, blocked или error. usage несёт только счётчики токенов — input, output, reasoning, cacheRead, cacheWrite — и целиком опускается, если счётчики неизвестны. Поля стоимости нет. Если прогон завершается ошибкой до отправки (неверный флаг, неизвестная модель и так далее), формат потока печатает одну строку перед выходом:

{ "type": "error", "error": { "code": "usage", "message": "..." } }

Значение error.code — одно из следующих:

Коды выхода

Песочница

--sandbox read-only|workspace-write|full-access выбирает режим изоляции (по умолчанию full-access). В неинтерактивных прогонах запросы прав отклоняются автоматически и сообщаются как события permission_denied, поэтому прогон, которому нужна неразрешённая запись, сообщает blocked и завершается с кодом 3. Это покрывает и субагентов: запросы в дочерних сеансах, созданных инструментом task, отклоняются так же, а их события permission_denied несут дочерний sessionID. Вызовы инструментов, отклонённые правилом запрета прав (например из --disallowed-tools) или песочницей только для чтения, тоже считаются отказами. Интерактивные инструменты question и plan_exit в неинтерактивном прогоне всегда отключены, в том числе в возобновлённых сеансах. Используйте read-only, только если изменений не ожидается. workspace-write удерживает записи внутри проекта.

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

Структурированный вывод

-o/--output-file <path> записывает итоговый текст ассистента в файл. --output-schema <file> проверяет итоговый текст как JSON по файлу JSON Schema. Несовпадение сообщается как событие error со значением result.status error и кодом выхода

1. Файл схемы предварительно проверяется до запуска модели: нечитаемая, неразбираемая или не являющаяся объектом схема — это ошибка использования, и ничего не отправляется. При успехе разобранная схема также отправляется модели как формат вывода json_schema этого прогона, а сервер до двух раз повторяет недействительный ответ, прежде чем собственная итоговая проверка CLI сработает как последний рубеж. Итоговый вывод — сериализованный структурированный объект (одна строка JSON): именно его несут stdout, --output-file и result.text:

ax-code run --model qwen --output-schema ./answer.schema.json -- "Return a JSON object with a summary field"

Сеансы и возобновление

• -c/--continue — продолжить самый недавний сеанс.
• -s/--session <id> — продолжить конкретный сеанс по идентификатору.
• --fork — ответвить сеанс перед продолжением (нужен --continue или --session).
• --show-history — печатать видимую историю сеанса при возобновлении (нужен --continue или --session).
• --attach <url> — подключиться к уже работающему серверу вместо запуска нового. Сочетайте с --dir, чтобы указать каталог проекта на этом сервере. Сервер, защищённый через AX_CODE_SERVER_PASSWORD, принимает --password (или ту же переменную на стороне вызывающего). Управляемая среда выполнения берёт свой токен из AX_CODE_RUNTIME_TOKEN.
• --runtime — подключиться к управляемой среде выполнения каталога проекта (--dir или текущий каталог вызывающего), запущенной через ax-code runtime start, определяя URL и токен по закрытой записи среды выполнения. Если среда не запущена, прогон завершается ошибкой до любого запроса с кодом attach и сообщением, называющим команду запуска. --runtime и --attach взаимоисключающие.

Рецепты

Одноразовый запуск

ax-code run --model qwen -- "Fix the failing test in src/parser.ts"

Ограничение прогона тайм-аутом

ax-code run --timeout 120 --model qwen -- "Fix the failing test in src/parser.ts"

--timeout <seconds> прерывает прогон на сервере и завершается с кодом 124 (result.status равен timeout), если прогон переживает заданный предел, поэтому застрявший агент не может держать задание CI открытым бесконечно. Предел покрывает весь вызов: он взводится до первого обращения к серверу, так что даже недоступный узел --attach или зависший запуск завершаются вовремя (в этом раннем случае строка результата несёт пустой sessionID).

Ожидание фоновых субагентов

ax-code run --await-background 300 --timeout 360 --model qwen -- \
  "Delegate the independent checks, then integrate their results"

--await-background <seconds> держит этот вызов открытым для фоновых дочерних процессов task, созданных его сеансом, и для последующих ходов родителя, которые запускают их результаты. Режим включается явно и ограничен 3600 секундами. Итоговый ответ и JSON result.text берутся из последнего завершённого хода родителя. Если дочерние процессы или их продолжение не уложатся в предел ожидания, прогон сообщает об ошибке и завершается с кодом 1. --timeout остаётся общим пределом. Запланированные задачи проекта идут в отдельных сеансах и в это ожидание не входят. Эта одноразовая команда не забирает подошедшие расписания проекта: их диспетчеризацией владеет постоянный сервер.

Разбор потока JSON

result=$(ax-code run --format json --model qwen -- "..." | tail -n 1)
echo "$result" | jq -r '.status'
echo "$result" | jq -r '.text'

Строка result всегда последняя, поэтому tail -n 1 выделяет её, даже если поток оборвался раньше.

Проверка только для чтения

ax-code run --sandbox read-only --model qwen -- "Review this diff for bugs"

Структурированный вывод JSON со схемой

cat > answer.schema.json <<'JSON'
{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}
JSON
ax-code run --model qwen --output-schema answer.schema.json --output-file answer.json \
  -- "Return JSON with a one-sentence summary"

Возобновление сеанса

# Start a session and note the sessionID from the result line
ax-code run --format json --model qwen -- "Draft the outline" | tail -n 1

# Continue it
ax-code run --model qwen --session ses_... -- "Now write section 2"

Прикрепление файла

ax-code run --model qwen --file docs/spec.md -- "Summarize the attached spec"

Команды, читаемые машиной

ax-code run --format json выдаёт поток событий с разделителем-переводом строки (см. Поток JSON). Это единственная поверхность --json, которая передаёт поток. Любая другая команда только для чтения с флагом --json следует более строгому контракту: при успехе пишет в stdout ровно один документ JSON, а при неудаче stdout остаётся пустым, один документ {"error":{"code","message"}} уходит в stderr, и код выхода равен 1.

Команды с --json:

• ax-code session list --json
• ax-code models --json
• ax-code providers list --json
• ax-code agent list --json
• ax-code mcp list --json
• ax-code mcp auth list --json
• ax-code stats --json
• ax-code context --json
• ax-code memory status --json
• ax-code memory list --json
• ax-code task list --json / ax-code task show <taskID> --json
• ax-code schedule list --json / ax-code schedule show <taskID> --json
• ax-code runtime list --json / ax-code runtime status --json
• ax-code doctor --json
• ax-code risk <sessionID> --json
• ax-code wiki status --json
• ax-code workflow list --json / ax-code workflow status <runID> --json

ax-code runtime status печатает свой документ JSON безусловно: флаг --json принимается для единообразия, но действие статуса всегда выдаёт JSON в stdout.

Вызов ax-code из другого агента

Когда вы оборачиваете ax-code run сценарием, шагом CI или другим агентом:

• Используйте --format json и читайте последнюю строку: запись result всегда замыкает поток, даже если он оборвался раньше.
• Возьмите sessionID из этой строки результата для любого следующего хода и передайте его обратно через --session.
• Никогда не используйте --continue из параллельных вызывающих: команда возобновляет самый недавний сеанс и гоняется, когда несколько вызывающих активны одновременно. Передавайте явный идентификатор --session.
• Передавайте явный --model, чтобы прогон не зависел от изменяемого настроенного значения по умолчанию.
• Всегда передавайте --timeout, чтобы застрявший агент не держал вызывающего открытым.
• Закройте stdin или используйте --prompt-file / --prompt-file -: неявный читатель канала сдаётся после окна тишины 300 мс и молча обрезает медленный канал.
• Задайте NO_COLOR=1 или положитесь на определение не-TTY, чтобы прогон в канале никогда не выдавал escape-коды ANSI.
• Запускайте из каталога проекта: домашний каталог или родительский каталог нескольких репозиториев в неинтерактивном режиме отклоняется. Задайте AX_CODE_ALLOW_BROAD_DIR=1, чтобы переопределить эту защиту.
• Ошибки использования ничего не печатают в stdout (справка и однострочная ошибка идут в stderr), поэтому опечатанная команда оставляет stdout пустым с кодом выхода 1. При --format json ошибка использования также записывается одной строкой error в stdout.
• Сигнал, пришедший, пока процесс ещё загружается и команда run ещё не активна, завершает процесс с кодом выхода 130 и без вывода. Когда команда уже активна, SIGINT и SIGTERM всегда дают единственную завершающую строку result со статусом cancelled.