خودکارسازی و CI/CD

تسلط بر حالت بدون رابط Claude Code — مرجع کامل گزینه‌ها، پنج دستور کار CI/CD، جداسازی Docker، ازسرگیری نشست و مقایسه با Codex

به‌روزرسانی 2026-11-13

به کلید API نیاز دارید؟ ثبت‌نام ←نقاط پایانی و Base URL ←

در این صفحه

Claude Code از حالت بدون رابط پشتیبانی می‌کند که می‌توانید از آن در اسکریپت‌ها، خطوط لوله CI/CD و گردش‌کارهای خودکار بدون هیچ تعامل انسانی استفاده کنید. این مقاله مرجع کامل گزینه‌ها و چند سناریوی واقعی را پوشش می‌دهد.


1. استفاده پایه

اجرای یک‌باره (حالت -p)

# Basic run
claude -p "Analyse this project's architecture"

# JSON output
claude -p "List every TODO comment" --output-format json

# Cap the number of turns
claude -p "Write unit tests for UserService" --max-turns 5

# Pick a model (claude-sonnet-5 for everyday work; 4.x is still on sale)
claude -p "Review the code for security issues" --model claude-opus-5

محدود کردن ابزارهای در دسترس

# Read-only analysis (no writes, no command execution)
claude -p "Analyse code quality" --permission-mode dontAsk --allowedTools Read,Glob,Grep

# Read and write (no command execution)
claude -p "Refactor this file" --permission-mode dontAsk --allowedTools Read,Write,Edit,Glob,Grep

# All tools (controlled environment)
claude -p "Fix the lint errors" --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، حالت را صریحاً تنظیم کنید:

# only allow-listed tools run; everything else is denied without asking
claude -p "Fix the lint errors" --permission-mode dontAsk --allowedTools "Read,Edit,Bash(npm run lint:*)"

برای اطلاع از نحوه رفتار حالت auto از طریق QCode، دسترس‌پذیری قابلیت‌ها را ببینید.

رد کردن promptهای مجوز

# Only in a safe, isolated environment!
claude -p "Fix every lint error and commit" --dangerously-skip-permissions

هشدار امنیتی: --dangerously-skip-permissions همه تأییدهای مجوز را رد می‌کند. فقط داخل یک کانتینر Docker یا محیط CI ایزوله از آن استفاده کنید.


2. مرجع کامل فلگ‌ها

کنترل اجرا

فلگ کارکرد مثال
-p "prompt" حالت بدون رابط، اجرای یک وظیفه واحد claude -p "analyse the architecture"
--bare حالت حداقلی، هوک‌ها/LSP/افزونه‌ها را نادیده می‌گیرد 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 به‌عنوان فهرست مجاز عمل می‌کند
--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 — بازبینی کد با هوش مصنوعی

name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # full history, needed for the 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: |
          # Collect the files changed in this PR
          FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)

          claude -p "Review the code changes in the following files, focusing on:
          1. Security vulnerabilities (SQL injection, XSS, leaked secrets)
          2. Performance problems (N+1 queries, memory leaks)
          3. Logic errors
          4. Code style issues

          Changed files:
          $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 "Look at the .ts files under src/ and write unit tests for the ones that have none.
          Use Vitest + Testing Library.
          Name test files xxx.test.ts and put them next to the source file.
          Target 80%+ coverage." \
            --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 "Analyse code quality and output JSON:
          {
            \"score\": 0-100,
            \"issues\": [{\"severity\": \"high|medium|low\", \"file\": \"...\", \"description\": \"...\"}],
            \"summary\": \"one-line summary\"
          }

          Scoring:

          - Type safety (20 points)
          - Error handling (20 points)
          - Test coverage (20 points)
          - Readability (20 points)
          - Security (20 points)" \
            --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: تولید فهرست تغییرات

#!/bin/bash
# generate-changelog.sh — build a changelog from git commits

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"

# Commits since the last tag
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 "Produce a structured changelog from these git commits:

$COMMITS

Format:
## [version] - $(date +%Y-%m-%d)
### Added
### Fixed
### Changed
### Breaking changes (if any)

Write in English, concise and professional." \
  --output-format text \
  --max-turns 2 \
  --model claude-sonnet-5 \
  --permission-mode dontAsk \
  --allowedTools Read,Glob,Grep

دستورکار 5: به‌روز نگه‌داشتن مستندات

#!/bin/bash
# update-docs.sh — refresh the API docs after code changes

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"

claude -p "Look at the route files under src/api/ and compare them with the documentation in docs/api.md.
Find API descriptions that are missing or out of date and update docs/api.md.
Keep the existing document format and style." \
  --max-turns 8 \
  --permission-mode dontAsk \
  --allowedTools Read,Write,Edit,Glob,Grep

4. ایزوله‌سازی با Docker

وقتی از --dangerously-skip-permissions در CI/CD استفاده می‌کنید، اکیداً توصیه می‌کنیم داخل یک کانتینر Docker اجرا کنید:

FROM node:22-slim

# Install Claude Code
RUN npm install -g @anthropic-ai/claude-code

# Install project dependencies
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

# QCode.cc environment
ENV ANTHROPIC_BASE_URL=https://api.qcode.cc/api
# ANTHROPIC_AUTH_TOKEN is injected at runtime

# Run as a non-root user
RUN useradd -m claude
USER claude

CMD ["claude", "-p", "Run a code review", "--dangerously-skip-permissions", "--max-turns", "5"]

آن را اجرا کنید:

docker build -t claude-ci .
docker run --rm -e ANTHROPIC_AUTH_TOKEN=cr_your_key claude-ci

5. ادامه نشست و خطوط لوله چندمرحله‌ای

وظایف چندمرحله‌ای

# Step 1: analyse
claude -p "Analyse the project architecture" \
  --session-id "pipeline-42" \
  --output-format json \
  --max-turns 3 \
  --permission-mode dontAsk \
  --allowedTools Read,Glob,Grep

# Step 2: build a plan from that analysis
claude -p "Based on the previous analysis, draft a refactoring plan" \
  --resume --session-id "pipeline-42" \
  --max-turns 3

# Step 3: execute the plan
claude -p "Carry out the first step of the refactoring plan" \
  --resume --session-id "pipeline-42" \
  --max-turns 10 \
  --permission-mode dontAsk \
  --allowedTools Read,Write,Edit,Bash,Glob,Grep

6. کنترل هزینه

راهبرد 1: محدود کردن نوبت‌ها

# Three turns is enough for a simple task
claude -p "Quick analysis" --max-turns 3

# Ten at most for a complex one
claude -p "Full refactor" --max-turns 10

راهبرد 2: انتخاب مدل مناسب

سناریو پیشنهادی دلیل
بازبینی کد Sonnet به‌اندازه کافی خوب و ارزان
اسکن امنیتی Opus به تحلیل عمیق نیاز دارد
قالب‌بندی انبوه Haiku ارزان‌ترین
تولید تست Sonnet بهترین نسبت ارزش
claude -p "Format the code" --model claude-haiku-5-5 --max-turns 3

راهبرد 3: محدود کردن ابزارها برای کاهش مصرف توکن

# Read-only analysis → no repeated write/test cycles to pay for
claude -p "Analyse the code" --permission-mode dontAsk --allowedTools Read,Glob,Grep --max-turns 3

7. مقایسه با Codex Headless

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. چک‌لیست بهترین روش‌ها

  1. همیشه نوبت‌ها را محدود کنید: در CI از --max-turns استفاده کنید تا از اجرای بی‌مهار جلوگیری شود
  2. ابزارها را محدود کنید: فقط آنچه وظیفه نیاز دارد را با --permission-mode dontAsk + --allowedTools مجاز کنید (یا ابزارهای در دسترس را با --tools محدود کنید)
  3. با Docker ایزوله کنید: --dangerously-skip-permissions باید در یک کانتینر اجرا شود
  4. خروجی JSON: در خودکارسازی، --output-format json را ترجیح دهید تا تجزیه نتایج آسان باشد
  5. کنترل هزینه: Sonnet برای تحلیل، Haiku برای وظایف ساده
  6. تکرارپذیری بدون اثر جانبی: مطمئن شوید اجراهای مکرر اثر جانبی ندارند
  7. مهلت‌های زمانی: در خط لوله یک مهلت زمانی برای کار تعیین کنید (مثلاً 10 دقیقه)
  8. مدیریت اسرار: کلید API را در اسرار CI نگه دارید و هرگز آن را در کد ثابت نکنید

گام‌های بعدی

با QCode شروع کنید

یک کلید API برای Claude Code، Codex و بیشتر — بر اساس توکن، قیمت هر مدل در qcode.cc/models

سازمانی ←