Chạy Claude Code không giao diện (claude -p): đưa agent vào script, cron và CI

Claude Code không chỉ là công cụ chat trong terminal. Thêm cờ -p là nó trở thành một lệnh CLI bình thường: nhận prompt, làm việc, in kết quả ra stdout rồi thoát — đủ để đưa vào script, cron job, Git hook hay pipeline CI. Bài này hướng dẫn từ lệnh cơ bản tới cấu hình an toàn cho chạy tự động.

Lệnh cơ bản

claude -p "Module auth làm gì?"

-p (hay --print) chạy không tương tác. Claude Code trả exit code 0 khi thành công và khác 0 khi thất bại, nên script của bạn rẽ nhánh được. Lỗi trong lúc chạy (ví dụ thiếu xác thực) được in ra stdout như kết quả.

Pipe dữ liệu vào và ra

# Giải thích log build lỗi
cat build-error.txt | claude -p "Giải thích ngắn gọn nguyên nhân gốc của lỗi build này" > output.txt

# Viết changelog từ commit hôm nay
git log --since=midnight --oneline | claude -p "Viết changelog ngắn, nhóm theo feature/fix"

stdin pipe vào tối đa 10 MB; dữ liệu lớn hơn thì ghi ra file và nhắc tên file trong prompt.

Chế độ --bare: nên dùng cho script và CI

Mặc định claude -p tự nạp hook, skill, subagent, plugin, MCP server, auto memory và CLAUDE.md giống phiên tương tác — kể cả trong thư mục bạn chưa từng tin cậy, và không hiện hộp thoại trust nào. Thêm --bare để bỏ qua toàn bộ việc tự dò đó:

claude --bare -p "Tóm tắt README.md" --allowedTools "Read"

• Khởi động nhanh hơn, kết quả giống nhau trên mọi máy — hook trong ~/.claude của đồng nghiệp hay MCP trong .mcp.json của repo sẽ không chạy.
• Không đọc OAuth hay keychain: cần đặt ANTHROPIC_API_KEY (hoặc thông tin xác thực Bedrock / Google Cloud / Foundry).
• Thứ cần dùng thì truyền tường minh: --append-system-prompt, --settings, --mcp-config, --agents, --plugin-dir.

Tài liệu chính thức khuyến nghị --bare cho mọi lời gọi từ script/SDK, và cho biết nó sẽ thành mặc định của -p trong tương lai.

Lấy kết quả có cấu trúc

# Lấy riêng phần text kết quả
claude -p "Tóm tắt dự án" --output-format json | jq -r '.result'

# Ép output theo JSON Schema
claude -p "Liệt kê tên các hàm chính trong auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

Kết quả theo schema nằm trong trường structured_output. Nếu Claude từ chối hoặc không tạo được output hợp lệ thì trường này không có — script phải kiểm tra trước khi dùng. Trường total_cost_usd giúp theo dõi chi phí từng lần chạy (là ước tính phía client).

Kiểm soát quyền — quan trọng nhất khi chạy tự động

Không có ai ngồi bấm “Allow”, nên phải nói trước Claude được làm gì:

# Chỉ cho phép đúng các lệnh git cần thiết
claude -p "Xem thay đổi đã stage và tạo commit phù hợp" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

• --allowedTools dùng cú pháp permission rule. Dấu * sau khoảng trắng cho phép mọi lệnh bắt đầu bằng tiền tố đó — Bash(git diff *) khác Bash(git diff*) (cái sau khớp cả git diff-index).
• Lời gọi cần duyệt mà không được cho phép sẽ bị từ chối (chế độ Manual mặc định cho -p ở phiên bản mới).
• --permission-mode đặt mức nền: dontAsk (từ chối mọi thứ cần hỏi — hợp CI khoá chặt), acceptEdits (tự sửa file và các lệnh file cơ bản), auto (một model phân loại duyệt thay bạn).
• --permission-prompts none cho job không người trực: không chờ ai trả lời, yêu cầu cần duyệt bị từ chối và Claude được báo không thử lại.

Tuỳ biến system prompt

# review.sh — review bảo mật một PR
gh pr diff "$1" | claude -p \
  --append-system-prompt "Bạn là kỹ sư bảo mật. Review các lỗ hổng." \
  --output-format json

--append-system-prompt thêm chỉ dẫn nhưng giữ hành vi mặc định của Claude Code; --system-prompt thay thế hoàn toàn.

Hội thoại nhiều lượt

# Lượt đầu
claude -p "Review codebase tìm vấn đề hiệu năng"
# Tiếp tục hội thoại gần nhất
claude -p "Giờ tập trung vào các truy vấn database" --continue

# Hoặc giữ session_id để quay lại đúng phiên
sid=$(claude -p "Bắt đầu review" --output-format json | jq -r '.session_id')
claude -p "Tiếp tục review đó" --resume "$sid"

Ứng dụng thực tế

An toàn khi chạy tự động

• Luôn khai báo --allowedTools tối thiểu; tránh bỏ qua toàn bộ quyền trên máy có dữ liệu thật.
• Dùng --bare trong CI để repo lạ không chạy được hook hay MCP của nó.
• Chạy trong container/runner riêng, dùng API key riêng cho automation, có spend limit; có thể chặn ngân sách mỗi lần chạy bằng --max-budget-usd.
• Kiểm tra exit code và sự có mặt của structured_output trước khi xử lý tiếp.
• Cần custom tool, callback duyệt quyền hay xử lý message chi tiết hơn → chuyển sang Claude Agent SDK (Python/TypeScript).

Áp dụng thế nào?

• Dev: Thêm script lint:claude pipe diff vào Claude để bắt lỗi chính tả/đặt tên trước khi mở PR — không cần cấp quyền Bash.
• Tech Lead: Chuẩn hoá một wrapper script cho CI: luôn --bare, luôn allowlist, luôn --output-format json, log total_cost_usd.
• PM: Đặt một cron 17h tổng hợp commit + ticket thành báo cáo ngày gửi vào kênh team — thay cho việc hỏi “hôm nay làm gì” trong standup.