خودکارسازی و CI/CD
تسلط بر حالت بدون رابط Claude Code — مرجع کامل گزینهها، پنج دستور کار CI/CD، جداسازی Docker، ازسرگیری نشست و مقایسه با Codex
به کلید 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. چکلیست بهترین روشها¶
- همیشه نوبتها را محدود کنید: در CI از
--max-turnsاستفاده کنید تا از اجرای بیمهار جلوگیری شود - ابزارها را محدود کنید: فقط آنچه وظیفه نیاز دارد را با
--permission-mode dontAsk+--allowedToolsمجاز کنید (یا ابزارهای در دسترس را با--toolsمحدود کنید) - با Docker ایزوله کنید:
--dangerously-skip-permissionsباید در یک کانتینر اجرا شود - خروجی JSON: در خودکارسازی،
--output-format jsonرا ترجیح دهید تا تجزیه نتایج آسان باشد - کنترل هزینه: Sonnet برای تحلیل، Haiku برای وظایف ساده
- تکرارپذیری بدون اثر جانبی: مطمئن شوید اجراهای مکرر اثر جانبی ندارند
- مهلتهای زمانی: در خط لوله یک مهلت زمانی برای کار تعیین کنید (مثلاً 10 دقیقه)
- مدیریت اسرار: کلید API را در اسرار CI نگه دارید و هرگز آن را در کد ثابت نکنید
گامهای بعدی¶
- سیستم Hooks — اقدامات را بهصورت خودکار فعال کنید
- نکات CLI — استفاده بیشتر از خط فرمان
- بهینهسازی هزینه — تکنیکهایی برای کنترل هزینهها
- آموزش کامل Claude Code — از صفر تا تسلط
با QCode شروع کنید
یک کلید API برای Claude Code، Codex و بیشتر — بر اساس توکن، قیمت هر مدل در qcode.cc/models