TL;DR

acpx 0.6.0 ra mắt 25/04/2026 (announce bởi @steipete). Đây là bản nâng cấp control-plane của headless CLI cho Agent Client Protocol (ACP), giúp orchestrator điều khiển Claude Code, Codex, Pi, OpenClaw và các coding agent khác qua giao thức structured thay vì PTY scraping.

Highlights: Claude system-prompt controls, session pruning, embeddable turn handles, --no-terminal, persistent-session fixes, WSL cwd translation, queue hardening, và clearer error hints. Không có breaking change — drop-in upgrade từ 0.5.x.

Có gì mới

  • System-prompt overrides cho Claude: hai cờ mới --system-prompt (replace) và --append-system-prompt (append). Inject persona, role hoặc constraints thẳng vào Claude session từ CLI hoặc orchestrator script, không phải đụng vào config file.
  • Session pruning: lệnh acpx sessions prune hỗ trợ --dry-run và filter theo age. Trước đây phải xoá tay; giờ pipeline có thể tự dọn session cũ định kỳ.
  • Embeddable turn handles: API startTurn(...) trả về handle cho embedder observe runtime events (token stream, tool calls, errors) tách biệt khỏi stdout của process. Phục vụ IDE và web app tích hợp ACP.
  • --no-terminal: disable ACP terminal capability — agent không thể spawn shell trong session. Một lớp sandbox đơn giản cho automation chạy untrusted prompt.
  • Adapter version ranges được bump để track Claude Code, Codex, Pi và các backend khác mới nhất.

Vì sao quan trọng

Khi muốn build automation trên Claude Code hay Codex, đa số dev đang phải scrape terminal output ký tự một — fragile, mất context, không stream tool calls đúng nghĩa. ACP đặt ra một giao thức structured để mọi agent nói cùng một ngôn ngữ; acpx là thứ biến giao thức đó thành công cụ chạy được hôm nay.

0.6.0 đẩy acpx từ "CLI client tử tế" sang "runtime nhúng được vào host khác": turn handles cho phép web app stream từng token và từng tool event, system-prompt controls cho phép orchestrator điều khiển persona theo từng turn, và --no-terminal khoá lại bề mặt tấn công khi chạy untrusted code.

Chi tiết kỹ thuật

Khu vực0.6.0 đem lại gì
Claude control--system-prompt, --append-system-prompt
Sessionssessions prune với --dry-run + age filter
EmbeddingstartTurn(...) turn handle, observe runtime events tách rời stdout
Sandboxing--no-terminal tắt ACP terminal capability
Persistent sessionsGiữ ACP client live giữa các turn; pooled clients đóng đúng; late updates drain trước khi close
Cross-platformwslpath translation cho Windows .exe agent chạy trên WSL
SecurityQueue + socket directory về owner-only; cryptographically random generation IDs; auth env phải ACPX_AUTH_* tường minh
DXError remediation hints rõ hơn cho auth, missing session, timeout, rate limit

So với phiên bản trước

Series 0.5.x tập trung móng cho embedding API: 0.5.0 stabilize prompt turns + flow definition validation, 0.5.1–0.5.3 sửa adapter launch, backend session closure on reset, bump Vite. Sang 0.6.0, hướng phát triển rẽ sang hai trục:

  • Observability + control (turn handles, system-prompt overrides) — phục vụ host nhúng acpx vào sản phẩm khác.
  • Operations (session pruning, security hardening, WSL fix) — phục vụ team chạy acpx ở scale, không còn là experiment trên máy 1 dev.

So với chạy claude hay codex CLI thuần: acpx cho NDJSON event stream, persistent multi-turn sessions có tên, có thể chạy parallel trên cùng repo, và programmable qua flow scripts. Trade-off: vẫn alpha, interfaces có thể đổi trước 1.0.

Use cases

  • Multi-agent orchestrator chạy Claude và Codex song song trên cùng repo, mỗi agent một named session.
  • Headless CI / automation: kết hợp --no-terminal với NDJSON output để gọi agent từ pipeline mà không lo agent nhảy ra spawn shell.
  • IDE / web app tích hợp ACP: dùng startTurn(...) để host observe live tokens và tool events, render UI riêng thay vì tail stdout.
  • Persona injection cho Claude: mỗi turn override system prompt theo role ("senior reviewer", "DBA", "security auditor") trực tiếp từ orchestrator.
  • Windows + WSL dev: gọi Codex .exe từ WSL mà cwd vẫn đúng repo path nhờ wslpath.
  • Hygiene: cron acpx sessions prune --older-than 30d để session state không phình disk.

Hạn chế & pricing

  • Vẫn alpha. Interfaces có thể breaking trước GA — đừng phụ thuộc cứng vào API trong production critical path.
  • Cần adapter cho mỗi agent; agent chưa support ACP phải dùng escape hatch --agent để chạy raw command.
  • Pricing: acpx open-source, miễn phí. Vẫn trả phí cho Claude API, Codex hoặc backend agent tương ứng.
  • No breaking changes trong 0.6.0 — upgrade npm install -g acpx@latest là xong.

Còn gì phía trước

Roadmap nhìn được: stabilize embedding API hướng tới 1.0 và mở rộng adapter list theo ACP Registry. Khi turn handles ổn định, kỳ vọng sẽ thấy IDE plugin, dashboard, và observability tool xây thẳng trên acpx runtime thay vì tự viết wrapper PTY.

Nguồn: @steipete trên X, openclaw/acpx releases, openclaw/acpx README.