Tác tử ACP

• Nếu plugins.allow được đặt, đó là một danh sách plugin hạn chế và phải bao gồm acpx; nếu không backend ACP đã cài đặt sẽ bị chặn có chủ ý và /acp doctor báo mục allowlist bị thiếu.
• Adapter Codex ACP được staging cùng plugin acpx và được khởi chạy cục bộ khi có thể.
• Các adapter harness đích khác vẫn có thể được tải theo nhu cầu bằng npx trong lần đầu bạn dùng chúng.
• Xác thực của nhà cung cấp vẫn phải tồn tại trên host cho harness đó.
• Nếu host không có npm hoặc quyền truy cập mạng, các lần tải adapter đầu tiên sẽ thất bại cho đến khi cache được làm nóng trước hoặc adapter được cài đặt theo cách khác.

ACP khởi chạy một tiến trình harness bên ngoài thật. OpenClaw sở hữu định tuyến, trạng thái tác vụ nền, phân phối, liên kết và chính sách; harness sở hữu đăng nhập nhà cung cấp, catalog model, hành vi hệ thống tệp và các công cụ gốc của nó.

Trước khi quy lỗi cho OpenClaw, hãy xác minh:

• /acp doctor báo backend đã bật và khỏe mạnh.
• Id đích được acp.allowedAgents cho phép khi allowlist đó được đặt.
• Lệnh harness có thể khởi động trên host Gateway.
• Xác thực nhà cung cấp hiện diện cho harness đó (claude, codex, gemini, opencode, droid, v.v.).
• Model đã chọn tồn tại cho harness đó - id model không dùng chung được giữa các harness.
• cwd được yêu cầu tồn tại và có thể truy cập, hoặc bỏ qua cwd và để backend dùng mặc định của nó.
• Chế độ quyền phù hợp với công việc. Các phiên không tương tác không thể nhấp lời nhắc quyền gốc, nên các lượt chạy lập trình nặng về ghi/thực thi thường cần một hồ sơ quyền ACPX có thể tiếp tục không cần giao diện.

• Sinh phiên tạo hoặc tiếp tục một phiên runtime ACP, ghi metadata ACP vào kho phiên OpenClaw và có thể tạo tác vụ nền khi lượt chạy thuộc sở hữu của parent.
• Các phiên ACP thuộc sở hữu của parent được xử lý như công việc nền ngay cả khi phiên runtime là persistent; hoàn tất và phân phối xuyên bề mặt đi qua bộ thông báo tác vụ parent thay vì hoạt động như một phiên chat hướng người dùng bình thường.
• Bảo trì tác vụ đóng các phiên ACP one-shot thuộc sở hữu của parent đã kết thúc hoặc mồ côi. Các phiên ACP persistent được giữ lại trong khi vẫn còn liên kết cuộc trò chuyện đang hoạt động; các phiên persistent cũ không có liên kết đang hoạt động bị đóng để chúng không thể được tiếp tục âm thầm sau khi tác vụ sở hữu đã xong hoặc bản ghi tác vụ của nó đã mất.
• Tin nhắn theo dõi đã liên kết đi thẳng tới phiên ACP cho đến khi liên kết được đóng, bỏ focus, đặt lại hoặc hết hạn.
• Các lệnh Gateway vẫn ở cục bộ. /acp ..., /status và /unfocus không bao giờ được gửi như văn bản prompt bình thường tới một harness ACP đã liên kết.
• cancel hủy lượt đang hoạt động khi backend hỗ trợ hủy; nó không xóa metadata liên kết hoặc phiên.
• close kết thúc phiên ACP theo góc nhìn của OpenClaw và xóa liên kết. Một harness vẫn có thể giữ lịch sử upstream của riêng nó nếu hỗ trợ tiếp tục.
• Worker runtime nhàn rỗi đủ điều kiện được dọn dẹp sau acp.runtime.ttlMinutes; metadata phiên đã lưu vẫn còn khả dụng cho /acp sessions.

Các trigger bằng ngôn ngữ tự nhiên nên định tuyến tới plugin Codex gốc khi nó được bật:

• "Liên kết kênh Discord này với Codex."
• "Gắn chat này vào thread Codex <id>."
• "Hiển thị các thread Codex, rồi liên kết thread này."

Liên kết cuộc trò chuyện Codex gốc là đường dẫn điều khiển chat mặc định. Các công cụ động của OpenClaw vẫn thực thi thông qua OpenClaw, trong khi các công cụ gốc Codex như shell/apply-patch thực thi bên trong Codex. Đối với sự kiện công cụ gốc Codex, OpenClaw chèn một relay hook gốc theo từng lượt để các hook plugin có thể chặn before_tool_call, quan sát after_tool_call và định tuyến sự kiện Codex PermissionRequest thông qua phê duyệt OpenClaw. Hook Codex Stop được relay tới OpenClaw before_agent_finalize, nơi plugin có thể yêu cầu thêm một lượt model trước khi Codex hoàn tất câu trả lời. Relay này vẫn cố ý bảo thủ: nó không thay đổi đối số công cụ gốc Codex hoặc viết lại bản ghi thread Codex. Chỉ dùng ACP rõ ràng khi bạn muốn mô hình runtime/phiên ACP. Ranh giới hỗ trợ Codex nhúng được ghi lại trong hợp đồng hỗ trợ harness Codex v1.

• openai-codex/* - tuyến OAuth/gói đăng ký PI Codex.
• openai/* cộng với agentRuntime.id: "codex" - runtime nhúng của app-server Codex gốc.
• /codex ... - điều khiển hội thoại Codex gốc.
• /acp ... hoặc runtime: "acp" - điều khiển ACP/acpx rõ ràng.

Các trigger nên định tuyến đến runtime ACP:

• "Chạy tác vụ này dưới dạng phiên Claude Code ACP một lần và tóm tắt kết quả."
• "Dùng Gemini CLI cho tác vụ này trong một luồng, rồi giữ các phần tiếp theo trong cùng luồng đó."
• "Chạy Codex qua ACP trong một luồng nền."

OpenClaw chọn runtime: "acp", phân giải harness agentId, liên kết với hội thoại hoặc luồng hiện tại khi được hỗ trợ, và định tuyến các lượt tiếp theo đến phiên đó cho đến khi đóng/hết hạn. Codex chỉ đi theo đường dẫn này khi ACP/acpx được nêu rõ hoặc plugin Codex gốc không khả dụng cho thao tác được yêu cầu.

Với sessions_spawn, runtime: "acp" chỉ được công bố khi ACP được bật, bên yêu cầu không bị sandbox, và một backend runtime ACP đã được tải. acp.dispatch.enabled=false tạm dừng việc tự động gửi luồng ACP nhưng không ẩn hoặc chặn các lệnh gọi sessions_spawn({ runtime: "acp" }) rõ ràng. Nó nhắm đến các id harness ACP như codex, claude, droid, gemini, hoặc opencode. Không truyền một id tác tử cấu hình OpenClaw thông thường từ agents_list trừ khi mục đó được cấu hình rõ ràng với agents.list[].runtime.type="acp"; nếu không, hãy dùng runtime tác tử con mặc định. Khi một tác tử OpenClaw được cấu hình với runtime.type="acp", OpenClaw dùng runtime.acp.agent làm id harness bên dưới.

• --bind here và --thread ... loại trừ lẫn nhau.
• --bind here chỉ hoạt động trên các kênh công bố khả năng liên kết hội thoại hiện tại; nếu không, OpenClaw trả về thông báo không được hỗ trợ rõ ràng. Các liên kết tồn tại qua các lần khởi động lại Gateway.
• Trên Discord, spawnSessions kiểm soát việc tạo luồng con cho --thread auto|here - không phải --bind here.
• Nếu bạn spawn đến một tác tử ACP khác mà không có --cwd, theo mặc định OpenClaw kế thừa không gian làm việc của tác tử đích. Các đường dẫn kế thừa bị thiếu (ENOENT/ENOTDIR) quay về mặc định backend; các lỗi truy cập khác (ví dụ EACCES) hiển thị dưới dạng lỗi spawn.
• Các lệnh quản lý Gateway vẫn cục bộ trong hội thoại được liên kết - các lệnh /acp ... do OpenClaw xử lý ngay cả khi văn bản tiếp theo thông thường định tuyến đến phiên ACP được liên kết; /status và /unfocus cũng vẫn cục bộ bất cứ khi nào xử lý lệnh được bật cho bề mặt đó.

Khi liên kết luồng được bật cho một bộ chuyển đổi kênh:

• OpenClaw liên kết một luồng với một phiên ACP đích.
• Tin nhắn tiếp theo trong luồng đó định tuyến đến phiên ACP được liên kết.
• Đầu ra ACP được gửi lại cùng luồng đó.
• Bỏ tập trung/đóng/lưu trữ/hết thời gian nhàn rỗi hoặc hết hạn theo tuổi tối đa sẽ xóa liên kết.
• /acp close, /acp cancel, /acp status, /status, và /unfocus là lệnh Gateway, không phải prompt gửi đến harness ACP.

Cờ tính năng bắt buộc cho ACP liên kết theo luồng:

• acp.enabled=true
• acp.dispatch.enabled được bật theo mặc định (đặt false để tạm dừng việc tự động gửi luồng ACP; các lệnh gọi sessions_spawn({ runtime: "acp" }) rõ ràng vẫn hoạt động).
• Bật spawn phiên luồng của bộ chuyển đổi kênh (mặc định: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Hỗ trợ liên kết luồng phụ thuộc vào từng bộ chuyển đổi. Nếu bộ chuyển đổi kênh đang hoạt động không hỗ trợ liên kết luồng, OpenClaw trả về thông báo không được hỗ trợ/không khả dụng rõ ràng.

• Bất kỳ bộ chuyển đổi kênh nào phơi bày khả năng liên kết phiên/luồng.
• Hỗ trợ tích hợp hiện tại: luồng/kênh Discord, chủ đề Telegram (chủ đề diễn đàn trong nhóm/siêu nhóm và chủ đề DM).
• Các kênh Plugin có thể thêm hỗ trợ thông qua cùng giao diện liên kết.

Phiên tương tác được dùng để tiếp tục trò chuyện trên một bề mặt chat hiển thị:

• /acp spawn ... --bind here ràng buộc cuộc trò chuyện hiện tại với phiên ACP.
• /acp spawn ... --thread ... ràng buộc một thread/chủ đề của kênh với phiên ACP.
• Các bindings[].type="acp" liên tục đã cấu hình định tuyến những cuộc trò chuyện khớp tới cùng phiên ACP.

Các tin nhắn tiếp theo trong cuộc trò chuyện đã ràng buộc được định tuyến trực tiếp tới phiên ACP, và đầu ra ACP được chuyển lại về cùng kênh/thread/chủ đề đó.

Những gì OpenClaw gửi tới harness:

• Các follow-up ràng buộc thông thường được gửi dưới dạng văn bản prompt, kèm tệp đính kèm chỉ khi harness/backend hỗ trợ.
• Các lệnh quản lý /acp và lệnh Gateway cục bộ được chặn trước khi dispatch ACP.
• Các sự kiện hoàn tất do runtime tạo được hiện thực hóa theo từng mục tiêu. Agent OpenClaw nhận envelope runtime-context nội bộ của OpenClaw; harness ACP bên ngoài nhận một prompt thuần với kết quả con và chỉ dẫn. Envelope thô <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> tuyệt đối không được gửi tới harness bên ngoài hoặc lưu bền dưới dạng văn bản transcript người dùng ACP.
• Các mục transcript ACP dùng văn bản kích hoạt mà người dùng thấy hoặc prompt hoàn tất thuần. Siêu dữ liệu sự kiện nội bộ vẫn được cấu trúc trong OpenClaw khi có thể và không được xem là nội dung chat do người dùng viết.

Các phiên ACP một lần do một lượt chạy agent khác spawn là con chạy nền, tương tự sub-agent:

• Cha yêu cầu công việc bằng sessions_spawn({ runtime: "acp", mode: "run" }).
• Con chạy trong phiên harness ACP riêng.
• Các lượt con chạy trên cùng lane nền dùng cho spawn sub-agent gốc, nên harness ACP chậm không chặn công việc main-session không liên quan.
• Báo cáo hoàn tất trả về qua đường dẫn thông báo task-completion. OpenClaw chuyển siêu dữ liệu hoàn tất nội bộ thành một prompt ACP thuần trước khi gửi tới harness bên ngoài, nên harness không thấy các marker ngữ cảnh runtime chỉ dành cho OpenClaw.
• Cha viết lại kết quả con bằng giọng trợ lý bình thường khi cần phản hồi hướng tới người dùng.

Không xem đường dẫn này là chat ngang hàng giữa cha và con. Con đã có kênh hoàn tất quay lại cha.

sessions_send có thể nhắm tới phiên khác sau khi spawn. Với các phiên ngang hàng thông thường, OpenClaw dùng đường dẫn follow-up agent-to-agent (A2A) sau khi tiêm tin nhắn:

• Chờ phản hồi của phiên mục tiêu.
• Tùy chọn cho phép requester và mục tiêu trao đổi một số lượt follow-up có giới hạn.
• Yêu cầu mục tiêu tạo tin nhắn thông báo.
• Chuyển thông báo đó tới kênh hoặc thread hiển thị.

Đường dẫn A2A đó là fallback cho các lượt gửi ngang hàng nơi người gửi cần một follow-up hiển thị. Nó vẫn bật khi một phiên không liên quan có thể thấy và nhắn tin tới mục tiêu ACP, ví dụ dưới các thiết lập tools.sessions.visibility rộng.

OpenClaw chỉ bỏ qua follow-up A2A khi requester là cha của con ACP một lần do chính nó sở hữu. Trong trường hợp đó, chạy A2A trên task completion có thể đánh thức cha bằng kết quả của con, chuyển tiếp phản hồi của cha trở lại con, và tạo vòng lặp echo cha/con. Kết quả sessions_send báo cáo delivery.status="skipped" cho trường hợp con được sở hữu đó vì đường dẫn hoàn tất đã chịu trách nhiệm cho kết quả.

Dùng resumeSessionId để tiếp tục một phiên ACP trước đó thay vì bắt đầu mới. Agent phát lại lịch sử trò chuyện của nó qua session/load, nên nó tiếp tục với đầy đủ ngữ cảnh của những gì đã có trước đó.

{
  "task": "Continue where we left off - fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

Các trường hợp sử dụng phổ biến:

• Bàn giao một phiên Codex từ laptop sang điện thoại - bảo agent tiếp tục từ nơi bạn đã dừng.
• Tiếp tục một phiên lập trình bạn đã bắt đầu tương tác trong CLI, giờ chạy headless qua agent của bạn.
• Tiếp tục công việc bị gián đoạn do gateway khởi động lại hoặc timeout khi nhàn rỗi.

Ghi chú:

• resumeSessionId chỉ áp dụng khi runtime: "acp"; runtime sub-agent mặc định bỏ qua trường chỉ dành cho ACP này.
• streamTo chỉ áp dụng khi runtime: "acp"; runtime sub-agent mặc định bỏ qua trường chỉ dành cho ACP này.
• resumeSessionId là id tiếp tục ACP/harness cục bộ trên host, không phải khóa phiên kênh OpenClaw; OpenClaw vẫn kiểm tra chính sách ACP spawn và chính sách agent mục tiêu trước khi dispatch, còn backend hoặc harness ACP sở hữu quyền cho việc tải id upstream đó.
• resumeSessionId khôi phục lịch sử trò chuyện ACP upstream; thread và mode vẫn áp dụng bình thường cho phiên OpenClaw mới bạn đang tạo, nên mode: "session" vẫn yêu cầu thread: true.
• Agent mục tiêu phải hỗ trợ session/load (Codex và Claude Code có hỗ trợ).
• Nếu không tìm thấy id phiên, spawn sẽ lỗi rõ ràng - không âm thầm fallback sang phiên mới.

Sau khi deploy gateway, hãy chạy kiểm tra end-to-end trực tiếp thay vì chỉ tin vào unit test:

1. Xác minh phiên bản gateway đã deploy và commit trên host mục tiêu.
2. Mở một phiên cầu nối ACPX tạm thời tới một agent live.
3. Yêu cầu agent đó gọi sessions_spawn với runtime: "acp", agentId: "codex", mode: "run", và tác vụ Reply with exactly LIVE-ACP-SPAWN-OK.
4. Xác minh accepted=yes, một childSessionKey thực, và không có lỗi validator.
5. Dọn dẹp phiên cầu nối tạm thời.

Giữ gate ở mode: "run" và bỏ qua streamTo: "parent" - mode: "session" gắn với thread và các đường dẫn stream-relay là những lượt tích hợp phong phú riêng.