Автоматизация и CI/CD
Полное освоение headless-режима Claude Code — справочник параметров, пять примеров CI/CD, изоляция в Docker, восстановление сессии и сравнение с Codex
Нужен API-ключ? Зарегистрироваться →Эндпоинты и Base URL →
Содержание
Claude Code поддерживает headless-режим: его можно использовать в скриптах, конвейерах CI/CD и автоматизированных процессах без участия человека. В статье собран полный справочник параметров и несколько реальных сценариев.
1. Базовое использование¶
Однократный запуск (режим -p)¶
# Обычный запуск
claude -p "Проанализируй архитектуру этого проекта"
# Вывод в формате JSON
claude -p "Перечисли все комментарии TODO" --output-format json
# Ограничить число ходов
claude -p "Напиши модульные тесты для UserService" --max-turns 5
# Указать модель (для повседневных задач подойдёт claude-sonnet-5; 4.x тоже в продаже)
claude -p "Проверь код на проблемы безопасности" --model claude-opus-5
Ограничение доступных инструментов¶
# Только чтение (без записи и выполнения команд)
claude -p "Проанализируй качество кода" --permission-mode dontAsk --allowedTools Read,Glob,Grep
# Чтение и запись (без выполнения команд)
claude -p "Отрефактори этот файл" --permission-mode dontAsk --allowedTools Read,Write,Edit,Glob,Grep
# Все инструменты (в контролируемом окружении)
claude -p "Исправь ошибки линтера" --permission-mode dontAsk --allowedTools Read,Write,Edit,Bash,Glob,Grep
--allowedToolsозначает «эти инструменты выполняются без запроса»; само по себе оно не ограничивает остальные инструменты. Приведённые выше примеры показывают только перечисленные инструменты потому, что идут в паре с--permission-mode dontAsk, который отвергает всё не перечисленное. Чтобы полностью скрыть остальные встроенные инструменты от Claude, используйте--tools, например--tools "Read,Edit,Bash"(будут предложены только эти три встроенных инструмента).
Задавайте режим разрешений явно (не полагайтесь на значение по умолчанию)¶
С Claude Code 2.1.285 claude -p и Agent SDK запускаются в auto, если режим разрешений не задан, в сессиях,
которые не получают флаги возможностей: действия, требующие одобрения, проверяет классификатор, и его запросы
(модель claude-sonnet-5) учитываются в вашем расходе. Подключение к QCode с ANTHROPIC_AUTH_TOKEN не даёт
Claude Code учётных данных для их получения (то же самое для контейнеров CI, которые каждый запуск стартуют
заново), поэтому именно это и есть значение по умолчанию для вашего CI. Для фиксированного и воспроизводимого
поведения в CI задавайте режим явно:
# только инструменты из белого списка выполняются; остальное отклоняется без запроса
claude -p "Fix the lint errors" --permission-mode dontAsk --allowedTools "Read,Edit,Bash(npm run lint:*)"
О том, как режим auto ведёт себя через QCode, см. Доступность функций.
Пропуск запросов на подтверждение¶
# Только в безопасном изолированном окружении!
claude -p "Исправь все ошибки линтера и закоммить" --dangerously-skip-permissions
Предупреждение о безопасности:
--dangerously-skip-permissionsпропускает все подтверждения прав. Используйте его только в контейнере Docker или изолированном окружении CI.
2. Полный справочник параметров¶
Управление выполнением¶
| Параметр | Описание | Пример |
|---|---|---|
-p "prompt" |
Headless-режим, одна задача | claude -p "проанализируй архитектуру" |
--bare |
Минимальный режим, без hooks/LSP/plugins | claude --bare -p "..." |
--max-turns N |
Ограничение числа ходов | --max-turns 5 |
--model MODEL |
Выбор модели | --model claude-opus-5 |
--permission-mode MODE |
Задаёт режим разрешений (default / acceptEdits / plan / auto / dontAsk / bypassPermissions) |
--permission-mode dontAsk |
--dangerously-skip-permissions |
Пропустить все подтверждения | Только изолированное окружение |
Форматы вывода¶
| Параметр | Описание | Когда применять |
|---|---|---|
--output-format text |
Простой текст (по умолчанию) | Для чтения человеком |
--output-format json |
Структурированный JSON | Для скриптов |
--output-format stream-json |
Потоковый JSON | Обработка в реальном времени |
Ограничение инструментов¶
| Параметр | Описание |
|---|---|
--allowedTools Tool1,Tool2 |
Предварительное одобрение: перечисленные инструменты выполняются без запроса (остальные инструменты не ограничиваются) |
--permission-mode dontAsk |
Отклонять всё, что не одобрено заранее, без запроса; в паре с --allowedTools работает как allow-список |
--tools Tool1,Tool2 |
Предлагать Claude только перечисленные встроенные инструменты (настоящее ограничение) |
--disallowedTools Tool1 |
Убрать перечисленные инструменты из доступных |
Доступные имена инструментов: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Agent, NotebookEdit
Управление сессиями¶
| Параметр | Описание |
|---|---|
--session-id ID |
Задать идентификатор сессии |
--resume |
Возобновить предыдущую сессию |
Переменные окружения¶
| Переменная | Описание |
|---|---|
ANTHROPIC_BASE_URL |
Эндпоинт API (QCode.cc: https://api.qcode.cc/api) |
ANTHROPIC_AUTH_TOKEN |
API-ключ (начинается с cr_) |
CLAUDE_CODE_MAX_TURNS |
Число ходов по умолчанию |
CLAUDE_CODE_OUTPUT_FORMAT |
Формат вывода по умолчанию |
CLAUDE_MODEL |
Модель по умолчанию |
3. Практика CI/CD¶
Пример 1: GitHub Actions — AI-ревью кода¶
name: AI Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # полная история, нужна для diff
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: AI Code Review
env:
ANTHROPIC_BASE_URL: "https://api.qcode.cc/api"
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
# Получаем файлы, изменённые в PR
FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
claude -p "Проверь изменения кода в следующих файлах, обрати внимание на:
1. Уязвимости безопасности (SQL-инъекции, XSS, утечки секретов)
2. Проблемы производительности (N+1 запросы, утечки памяти)
3. Логические ошибки
4. Проблемы стиля кода
Изменённые файлы:
$FILES" \
--output-format json \
--max-turns 3 \
--model claude-sonnet-5 \
--permission-mode dontAsk \
--allowedTools Read,Glob,Grep \
> review.json
echo "Review completed"
cat review.json | jq -r '.result' || cat review.json
Пример 2: автоматическая генерация тестов¶
name: Auto Generate Tests
on:
push:
paths: ['src/**/*.ts', '!src/**/*.test.ts']
jobs:
generate-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install dependencies
run: |
npm ci
npm install -g @anthropic-ai/claude-code
- name: Generate missing tests
env:
ANTHROPIC_BASE_URL: "https://api.qcode.cc/api"
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
claude -p "Просмотри файлы .ts в src/ и напиши модульные тесты для тех, у которых их нет.
Используй Vitest + Testing Library.
Файлы тестов называй xxx.test.ts и клади рядом с исходником.
Целевое покрытие — от 80%." \
--max-turns 10 \
--permission-mode dontAsk \
--allowedTools Read,Write,Glob,Grep,Bash
- name: Run tests
run: npx vitest --run
- name: Create PR with tests
if: success()
run: |
git config user.name "claude-bot"
git config user.email "bot@qcode.cc"
git checkout -b auto-tests-$(date +%s)
git add '*.test.ts'
git commit -m "test: auto-generated unit tests" || exit 0
git push origin HEAD
Пример 3: контроль качества кода¶
name: Code Quality Gate
on: [pull_request]
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- run: npm install -g @anthropic-ai/claude-code
- name: Quality Analysis
env:
ANTHROPIC_BASE_URL: "https://api.qcode.cc/api"
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
claude -p "Проанализируй качество кода и выведи JSON:
{
\"score\": 0-100,
\"issues\": [{\"severity\": \"high|medium|low\", \"file\": \"...\", \"description\": \"...\"}],
\"summary\": \"итог одной строкой\"
}
Критерии оценки:
- Типобезопасность (20 баллов)
- Обработка ошибок (20 баллов)
- Покрытие тестами (20 баллов)
- Читаемость (20 баллов)
- Безопасность (20 баллов)" \
--output-format json \
--max-turns 3 \
--model claude-sonnet-5 \
--permission-mode dontAsk \
--allowedTools Read,Glob,Grep \
> quality.json
- name: Check score
run: |
SCORE=$(cat quality.json | jq -r '.result' | jq -r '.score // 0')
echo "Quality score: $SCORE"
if [ "$SCORE" -lt 60 ]; then
echo "Quality gate failed: score $SCORE < 60"
exit 1
fi
Пример 4: автогенерация Changelog¶
#!/bin/bash
# generate-changelog.sh — собрать changelog из коммитов git
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"
# Коммиты с момента последнего тега
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then
COMMITS=$(git log --oneline -20)
else
COMMITS=$(git log --oneline ${LAST_TAG}..HEAD)
fi
claude -p "Составь структурированный changelog по этим коммитам git:
$COMMITS
Формат:
## [версия] - $(date +%Y-%m-%d)
### Новое
### Исправления
### Улучшения
### Ломающие изменения (если есть)
Пиши по-русски, кратко и профессионально." \
--output-format text \
--max-turns 2 \
--model claude-sonnet-5 \
--permission-mode dontAsk \
--allowedTools Read,Glob,Grep
Пример 5: автоматическое обновление документации¶
#!/bin/bash
# update-docs.sh — обновить документацию API после изменений кода
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"
claude -p "Просмотри файлы маршрутов в src/api/ и сравни их с документацией в docs/api.md.
Найди описания API, которых не хватает или которые устарели, и обнови docs/api.md.
Сохрани текущий формат и стиль документа." \
--max-turns 8 \
--permission-mode dontAsk \
--allowedTools Read,Write,Edit,Glob,Grep
4. Изоляция через Docker¶
Если вы используете --dangerously-skip-permissions в CI/CD, настоятельно рекомендуем запускать всё в контейнере Docker:
FROM node:22-slim
# Устанавливаем Claude Code
RUN npm install -g @anthropic-ai/claude-code
# Устанавливаем зависимости проекта
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
# Переменные окружения QCode.cc
ENV ANTHROPIC_BASE_URL=https://api.qcode.cc/api
# ANTHROPIC_AUTH_TOKEN передаётся во время запуска
# Запуск от непривилегированного пользователя
RUN useradd -m claude
USER claude
CMD ["claude", "-p", "Выполни ревью кода", "--dangerously-skip-permissions", "--max-turns", "5"]
Запуск:
docker build -t claude-ci .
docker run --rm -e ANTHROPIC_AUTH_TOKEN=cr_your_key claude-ci
5. Восстановление сессии и многошаговые конвейеры¶
Многошаговые задачи¶
# Шаг 1: анализ
claude -p "Проанализируй архитектуру проекта" \
--session-id "pipeline-42" \
--output-format json \
--max-turns 3 \
--permission-mode dontAsk \
--allowedTools Read,Glob,Grep
# Шаг 2: на основе анализа составить план
claude -p "На основе предыдущего анализа составь план рефакторинга" \
--resume --session-id "pipeline-42" \
--max-turns 3
# Шаг 3: выполнить план
claude -p "Выполни первый шаг плана рефакторинга" \
--resume --session-id "pipeline-42" \
--max-turns 10 \
--permission-mode dontAsk \
--allowedTools Read,Write,Edit,Bash,Glob,Grep
6. Контроль расходов¶
Стратегия 1: ограничивайте число ходов¶
# Для простой задачи хватит трёх ходов
claude -p "Быстрый анализ" --max-turns 3
# Для сложной — не больше десяти
claude -p "Полный рефакторинг" --max-turns 10
Стратегия 2: выбирайте подходящую модель¶
| Сценарий | Рекомендуемая модель | Почему |
|---|---|---|
| Ревью кода | Sonnet | Достаточно и дёшево |
| Сканирование безопасности | Opus | Нужен глубокий анализ |
| Массовое форматирование | Haiku | Самая дешёвая |
| Генерация тестов | Sonnet | Лучшее соотношение цены и качества |
claude -p "Отформатируй код" --model claude-haiku-5-5 --max-turns 3
Стратегия 3: ограничивайте инструменты, чтобы тратить меньше токенов¶
# Анализ только на чтение → не будет циклов записи и тестов
claude -p "Проанализируй код" --permission-mode dontAsk --allowedTools Read,Glob,Grep --max-turns 3
7. Сравнение с headless-режимом Codex¶
| Параметр | Claude Code -p | Codex headless |
|---|---|---|
| Параметр запуска | -p "prompt" |
codex -q "prompt" |
| Песочница | Нужна изоляция через Docker | Встроенная песочница уровня ядра |
| Форматы вывода | text/json/stream-json | text/json |
| Восстановление сессии | --resume --session-id |
Не поддерживается |
| Ограничение инструментов | --tools / --permission-mode dontAsk + --allowedTools |
--approval-mode |
| Параллельное выполнение | Не поддерживается | codex cloud exec |
Как сочетать: Claude Code — для анализа и планирования (только чтение), Codex — для выполнения (полностью автоматически).
Тариф QCode.cc делит квоту между инструментами, поэтому переключение между ними в CI ничего не стоит.
8. Чек-лист лучших практик¶
- Всегда ограничивайте число ходов: в CI используйте
--max-turns, чтобы избежать бесконечного выполнения - Ограничивайте инструменты: разрешайте только необходимое через
--permission-mode dontAsk+--allowedTools(или ограничивайте доступные инструменты через--tools) - Изолируйте через Docker:
--dangerously-skip-permissionsдопустим только в контейнере - Вывод в JSON: в автоматизации удобнее
--output-format json - Контроль расходов: анализ — на Sonnet, простые задачи — на Haiku
- Идемпотентность: повторный запуск не должен давать побочных эффектов
- Таймауты: задайте job timeout в конвейере (например, 10 минут)
- Управление ключами: API-ключ храните в secrets CI, не зашивайте в код
Следующие шаги¶
- Система Hooks — автоматический запуск действий
- Приёмы работы в CLI — больше способов работы из командной строки
- Оптимизация расходов — приёмы контроля затрат
- Полное руководство по Claude Code — с нуля до уверенного владения
Начните с QCode
Один API-ключ для Claude Code, Codex и других инструментов; тарификация по токенам, цены каждой модели — на qcode.cc/models