Bài 8.118 phút · 5 thẻ · 8 bài tập · 1 nhiệm vụ

Headless claude -p và CI

Chạy Claude Code không người trông: quyền khi không ai trả lời, --bare, kết quả có cấu trúc, và GitHub Actions với chi phí trong tầm kiểm soát.

Từ đầu khóa tới giờ, Claude Code luôn có bạn ngồi trước màn hình: trả lời câu hỏi quyền, duyệt kế hoạch, nhấn Esc. Cấp cuối đưa nó ra khỏi terminal của bạn. Bài này chạy Claude Code không người trông: trong một script, một lệnh npm run, và trên GitHub Actions mỗi khi có pull request.

Claude Code không cần bạn ngồi trước

Thêm -p (hoặc --print) vào lệnh claude: Claude làm việc, in kết quả ra stdout rồi thoát.

Terminal
claude -p "What does src/routes/todos.js do?"

Ba điều làm -p dùng được trong script:

  • Mã thoát: 0 khi thành công, khác 0 khi lỗi, nên script rẽ nhánh được.
  • Đọc stdin: cat build-error.txt | claude -p "explain the root cause". Tối đa 10MB; lớn hơn thì ghi ra file và nhắc tên file trong prompt.
  • Định dạng output: --output-format text (mặc định), json (kèm session ID, số lượt, và total_cost_usd là chi phí ước tính), hoặc stream-json (từng sự kiện một).

Bạn đã thấy -p suốt khóa học: mọi chỗ "khi thử, chúng tôi…" đều là claude -p chạy trên một bản sao todo-api.

Quyền khi không ai trả lời

Trong phiên tương tác, lệnh cần quyền thì Claude Code hỏi bạn. Với -p không ai trả lời, nên mặc định (Manual mode) mọi thứ cần hỏi đều bị từ chối. Bạn phải nói trước Claude được làm gì:

  • --allowedTools theo cú pháp luật quyền ở bài 1.3 và 5.3: "Read,Edit", "Bash(npm test *)", "mcp__github__list_issues". Chú ý dấu cách trước *: Bash(git diff *) khớp git diff, còn Bash(git diff*) khớp cả git diff-index.
  • --permission-mode: acceptEdits cho phép sửa file, dontAsk từ chối hết những gì cần hỏi (hợp với CI khóa chặt), auto để bộ phân loại xét từng việc.
  • --permission-prompts none: báo cho Claude biết không ai duyệt được, đừng thử lại những gì bị từ chối.
  • --max-turns: giới hạn số lượt, để một lần chạy lỗi không chạy mãi.

Khi soạn khóa học, chúng tôi gặp đủ các kiểu bị từ chối: npm test chưa được cho phép, lệnh ghép nhiều phần cần duyệt riêng. Cách chữa luôn là liệt kê đúng công cụ cần, không hơn.

--bare cho script và CI

Không có --bare, claude -p nạp mọi thứ như một phiên bình thường: hook, skill, subagent, plugin, server MCP, CLAUDE.md của repo và của máy đang chạy. Có hai vấn đề:

  • Không lặp lại được: kết quả trên máy bạn khác trên máy CI, vì cấu hình khác nhau.
  • Không an toàn với repo lạ: như bài 5.2 và 6.1, -p chạy hook và nối server MCP của repo mà không hỏi.

--bare bỏ qua tất cả, chỉ nạp những gì bạn đưa bằng cờ: --append-system-prompt, --settings, --mcp-config, --agents, --plugin-dir. Docs khuyên dùng --bare cho script và CI, và nói nó sẽ thành mặc định của -p.

Một điều quan trọng chúng tôi kiểm chứng: --bare không dùng đăng nhập subscription của bạn. Trên máy đăng nhập bằng tài khoản Claude, claude --bare -p … thoát ngay với Not logged in · Please run /login. Cần đặt ANTHROPIC_API_KEY, khóa tạo trong Claude Console, và khi đó bạn trả tiền theo API.

Kết quả có cấu trúc

Một script cần dữ liệu, không cần một đoạn văn. Dùng --output-format json kèm --json-schema:

Terminal
claude -p "List every HTTP route in src/routes/todos.js with its status codes" \
  --output-format json --allowedTools "Read" \
  --json-schema '{"type":"object","properties":{"routes":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"statuses":{"type":"array","items":{"type":"integer"}}},"required":["method","path","statuses"]}}},"required":["routes"]}' \
  | jq '.structured_output.routes'

Khi thử, structured_output trả về đúng năm route của todo-api, mỗi route kèm danh sách mã trạng thái, và lần chạy tốn khoảng 0,21 USD theo total_cost_usd. Nhớ kiểm tra structured_output có tồn tại trước khi dùng: nếu Claude từ chối yêu cầu thì trường này không có.

Một mẫu nhỏ mà hữu ích từ docs, đặt trong package.json:

JSON
"lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""

Diff được đưa vào qua stdin nên Claude không cần quyền Bash. Chúng tôi cài một lỗi chính tả "requried" vào thông báo lỗi; npm run lint:claude trả đúng hai dòng: vị trí src/routes/todos.js:21 và từ cần sửa.

Lên GitHub Actions

Cách chính thức là action anthropics/claude-code-action@v1. Cài nhanh bằng /install-github-app trong Claude Code (cần GitHub CLI và quyền admin repo), hoặc tự thêm workflow và secret. Action có hai chế độ:

  • Interactive: không có prompt. Claude chờ ai đó gõ @claude trong issue hay PR rồi làm theo, trả lời bằng comment.
  • Automation: có prompt. Claude chạy ngay khi sự kiện xảy ra, ví dụ mỗi khi mở PR; kết quả mặc định nằm trong log của workflow.

Workflow @claude cho todo-api, theo mẫu docs, thêm giới hạn thời gian và số lượt:

YAML
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: "--max-turns 10"

Muốn review mọi PR tự động, docs có mẫu cài plugin code-review và chạy prompt: "/code-review:code-review --comment …". Skill trong .claude/skills/ của repo cũng chạy được: actions/checkout trước, rồi prompt: "/tên-skill".

Hai lớp bảo vệ có sẵn: chỉ người có quyền ghi repo mới kích hoạt được, và bot bị từ chối trừ khi bạn cho phép, để tránh vòng lặp bot gọi bot. Với repo công khai, GitHub không đưa secret cho PR từ fork, nên review tự động chỉ chạy với PR từ nhánh trong repo.

Chi phí và an toàn trên CI

Mỗi lần chạy tốn hai thứ: phút GitHub Actions và token. Docs gợi ý giữ cả hai trong tầm kiểm soát:

  • Đặt --max-turns trong claude_args, timeout-minutes cho job, và concurrency để không chạy chồng.
  • Giữ CLAUDE.md ngắn, vì nó được đọc ở mọi lần chạy.
  • Yêu cầu @claude cụ thể để Claude cần ít lượt hơn.

Về an toàn, áp dụng mọi thứ đã học:

  • Khóa chỉ nằm trong GitHub Secrets, không bao giờ trong repo.
  • Quyền của workflow tối thiểu: workflow chỉ review thì chỉ cần quyền read.
  • Xem lại trước khi merge: Claude mở PR, con người duyệt.
  • Hook và luật deny của cấp 5, 6 nằm trong repo, nên một lần chạy không có --bare sẽ nạp chúng. Xem log của lần chạy đầu để chắc chúng thật sự có hiệu lực trên CI.

Bài sau, 8.2, giải quyết chuyện cuối cùng: làm sao đưa toàn bộ bộ công cụ bạn xây suốt khóa học (skill, subagent, hook, MCP) sang repo khác và cho cả team chỉ bằng một lệnh cài.

Luyện tập bài 8.1

5 thẻ ghi nhớ, 8 bài tập chấm ngay trên trang, 1 nhiệm vụ làm trên máy.

Bắt đầu luyện tập

Tra cứu liên quan

Gõ để tìm trong tra cứu, mẫu cấu hình và bài học. Không dấu cũng được.