Форматы вывода: json / text / stream-json

Используйте --output-format у claude -p для обработки вывода Claude Code в скриптах и CI — разбор структурированного json, потоковые события stream-json в реальном времени, простой текст по умолчанию, с примерами jq и пайпов

Форматы вывода: json / text / stream-json¶

В скриптах, CI/CD и автоматизированных конвейерах нужен не просто «читаемый человеком» ответ, а структурированные данные, которые может разобрать программа. Headless-режим Claude Code (claude -p) предлагает три формата вывода через --output-format, позволяя встроить Claude Code в конвейер как обычный CLI-инструмент.

Это возможность самого Claude Code, и она не зависит от апстрима: указывает ли Claude Code на официальный API или на QCode, --output-format работает одинаково. Эта страница посвящена форматам вывода; полный справочник headless-флагов и шаблоны CI смотрите в Автоматизация и CI/CD.

1. Три формата кратко¶

# text — это значение по умолчанию, поэтому две строки ниже эквивалентны
claude -p "Объясни идемпотентность одним предложением"
claude -p "Объясни идемпотентность одним предложением" --output-format text

2. text: простой текст по умолчанию¶

Без --output-format вы получаете text: stdout — это просто финальный ответ модели, удобно читать напрямую или передать в простой пайп.

# Читать напрямую
claude -p "Перепиши эту функцию в async-форме"

# Передать другому инструменту
claude -p "Сгенерируй 5 вариантов commit message" | head -5

# Записать в файл
claude -p "Напиши краткое введение в README для этого репозитория" > intro.txt

Ограничение: text даёт только «ответ» — без стоимости, расхода токенов и ID сессии, а в многошаговых задачах нельзя отделить промежуточный процесс от итога. Когда это нужно, переключайтесь на json или stream-json.

3. json: один структурированный объект¶

--output-format json выводит один JSON-объект после завершения задачи, содержащий финальный результат и набор полей метаданных. Это самый используемый в скриптах формат.

claude -p "Посчитай количество комментариев TODO в src/" --output-format json

Типичные поля возвращаемого объекта (фактические поля зависят от вывода вашей версии):

Разбор с помощью jq¶

Формат json идеально подходит для jq:

# Только финальный ответ
claude -p "Опиши это изменение одним предложением" --output-format json | jq -r '.result'

# Извлечь стоимость этого вызова
claude -p "Проверь auth.py" --output-format json | jq '.total_cost_usd'

# Получить несколько полей сразу
claude -p "Проанализируй архитектуру" --output-format json \
  | jq '{cost: .total_cost_usd, session: .session_id, tokens: .usage}'

Ветвление и накопление стоимости в скрипте¶

#!/usr/bin/env bash
set -euo pipefail

out=$(claude -p "Напиши юнит-тесты для UserService" \
        --output-format json --max-turns 8)

result=$(echo "$out" | jq -r '.result')
cost=$(echo "$out"   | jq -r '.total_cost_usd')
sid=$(echo "$out"    | jq -r '.session_id')

echo "Результат: $result"
echo "Стоимость вызова: \$$cost"
echo "ID сессии: $sid (продолжить: claude --resume $sid)"

Совет: json выдаёт весь объект разом по завершении задачи — во время долгой задачи вывода нет. Чтобы следить за прогрессом вживую, используйте stream-json ниже.

4. stream-json: поток событий в реальном времени¶

--output-format stream-json разбивает выполнение на JSON-события, разделённые переводами строк (NDJSON), по одному событию на строку, записывая их немедленно. Подходит для прогресса долгих задач в реальном времени, потоковых UI или конвейеров, потребляющих вывод по мере его появления.

claude -p "Отрефактори весь каталог utils и добавь тесты" \
  --output-format stream-json --max-turns 20

Вывод выглядит так (каждая строка — независимый JSON; поля зависят от вашей версии):

{"type":"system","subtype":"init","session_id":"..."}
{"type":"assistant","message":{...}}
{"type":"assistant","message":{...}}
{"type":"result","result":"...","total_cost_usd":0.0123,"usage":{...}}

Потребление построчно¶

Каждая строка — корректный JSON, поэтому её можно обрабатывать по мере поступления:

# Печатать тип каждого события в реальном времени
claude -p "Мигрируй на новый API" --output-format stream-json \
  | jq -r '.type'

# Извлечь результат и стоимость только при появлении финального события
claude -p "Мигрируй на новый API" --output-format stream-json \
  | jq -r 'select(.type == "result") | "\(.result)\nСтоимость $\(.total_cost_usd)"'

# Обработка построчно в цикле while для живой обратной связи о прогрессе
claude -p "Ревью кода по всему репозиторию" --output-format stream-json | \
while IFS= read -r line; do
  type=$(echo "$line" | jq -r '.type')
  case "$type" in
    system) echo "▶ Запуск…" ;;
    assistant) echo "… думаю" ;;
    result) echo "✓ Готово: $(echo "$line" | jq -r '.result')" ;;
  esac
done

json vs stream-json: json ждёт завершения задачи и даёт один полный объект — разбирать просто; stream-json потоково выдаёт множество событий на протяжении всего выполнения, обеспечивая живую обратную связь, но требуя построчного разбора. В CI используйте json для финального результата и stream-json для логов прогресса.

5. Примеры для CI / конвейеров¶

Получить результат и опубликовать комментарий в GitHub Actions¶

- name: Ревью Claude
  env:
    ANTHROPIC_BASE_URL: https://api.qcode.cc/api
    ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
  run: |
    out=$(claude -p "Проверь diff этого PR и перечисли проблемы" \
            --output-format json --max-turns 6 --allowedTools Read,Glob,Grep)
    echo "$out" | jq -r '.result' > review.md
    echo "Это ревью стоило \$$(echo "$out" | jq -r '.total_cost_usd')"

Добавить контроль стоимости (падать при превышении бюджета)¶

out=$(claude -p "Сгенерируй заметки о релизе" --output-format json)
cost=$(echo "$out" | jq -r '.total_cost_usd')
# Сравнение с плавающей точкой через awk: уронить CI, если больше $0.50
awk -v c="$cost" 'BEGIN{ exit (c > 0.5) ? 1 : 0 }' \
  || { echo "Стоимость \$$cost превысила бюджет"; exit 1; }
echo "$out" | jq -r '.result'

Суммировать стоимость нескольких вызовов¶

total=0
for f in src/*.py; do
  out=$(claude -p "Напиши docstring для $f" --output-format json)
  c=$(echo "$out" | jq -r '.total_cost_usd')
  total=$(awk -v t="$total" -v c="$c" 'BEGIN{ printf "%.4f", t + c }')
done
echo "Суммарная стоимость по всем файлам: \$$total"

Указать на QCode: команды выше одинаковы для официального API и QCode — просто направьте ANTHROPIC_BASE_URL на https://api.qcode.cc/api (внимание: без слеша в конце) и впишите свой ключ cr_ в ANTHROPIC_AUTH_TOKEN. Пользователи в Китае могут использовать asia.qcode.cc. Подробнее в Точки доступа и форматы API.

6. Частые ошибки¶

• json молчит во время долгих задач: он выводит один раз, в конце — отсутствие прогресса нормально; для прогресса используйте stream-json.
• Нельзя jq по stream-json целиком: это NDJSON; несколько объектов не образуют единый JSON-документ. Используйте построчный jq, jq -c или --stream — не запускайте jq '.' по всему потоку.
• Не забывайте --max-turns: ограничивайте число ходов в автоматизации, чтобы задача не вышла из-под контроля и не сожгла деньги.
• Никакого слеша в конце BASE_URL: https://api.qcode.cc/api корректно; лишний / соберёт неверный путь.
• Поля метаданных зависят от версии: доверяйте реальному выводу claude -p ... --output-format json на вашей машине — сначала запустите jq 'keys', чтобы увидеть, какие поля есть.

Дальше¶

• Автоматизация и CI/CD — полный справочник headless-флагов и примеры CI/CD
• Субагенты — пусть Claude Code оркеструет фоновые агенты параллельно
• Оптимизация затрат — управляйте стоимостью через total_cost_usd
• Точки доступа и форматы API — четыре домена и пути протоколов

Встроив Claude Code в конвейер, вы видите стоимость прямо в выводе — смотрите тарифы и цены QCode и выберите план под ваш объём автоматизации.