Chuyển đến nội dung chính
Các phiên Agent Client Protocol (ACP) cho phép OpenClaw chạy các môi trường điều phối lập trình bên ngoài (Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI và các môi trường ACPX được hỗ trợ khác) thông qua Plugin backend ACP. Mỗi lần khởi tạo được theo dõi dưới dạng một tác vụ nền.
ACP là đường dẫn dành cho môi trường điều phối bên ngoài, không phải đường dẫn Codex mặc định. Plugin app-server Codex gốc sở hữu các điều khiển /codex ... và runtime nhúng openai/gpt-* mặc định cho các lượt của tác nhân; ACP sở hữu các điều khiển /acp ... và các phiên sessions_spawn({ runtime: "acp" }).Để cho phép Codex hoặc Claude Code kết nối trực tiếp dưới dạng máy khách MCP bên ngoài với các cuộc hội thoại kênh OpenClaw hiện có, hãy dùng openclaw mcp serve thay cho ACP.

​
Tôi cần trang nào?

​
Tính năng này có hoạt động ngay không?

Có, sau khi cài đặt Plugin runtime ACP chính thức:
Các bản checkout mã nguồn có thể dùng Plugin workspace extensions/acpx cục bộ sau pnpm install. Chạy /acp doctor để kiểm tra trạng thái sẵn sàng. OpenClaw chỉ hướng dẫn tác nhân về việc khởi tạo ACP khi ACP thực sự khả dụng: ACP phải được bật, việc điều phối không được tắt, phiên hiện tại không được sandbox chặn và một backend runtime phải được tải cũng như hoạt động bình thường. Nếu bất kỳ điều kiện nào không đạt, Skills ACP và hướng dẫn ACP sessions_spawn sẽ tiếp tục bị ẩn để tác nhân không đề xuất một backend không khả dụng.
  • Nếu plugins.allow được đặt, đây là 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ủ đích (/acp doctor báo cáo mục bị thiếu trong danh sách cho phép).
  • Bộ điều hợp Codex ACP được cung cấp cùng Plugin acpx và khởi chạy cục bộ khi có thể.
  • Codex ACP chạy với CODEX_HOME biệt lập. OpenClaw sao chép các mục tin cậy của dự án đáng tin cậy cùng cấu hình định tuyến mô hình/nhà cung cấp an toàn (model, model_provider, model_reasoning_effort, sandbox_mode và các trường model_providers.<name> an toàn) từ cấu hình Codex trên máy chủ; thông tin xác thực, thông báo và hook chỉ nằm trong cấu hình máy chủ.
  • Các bộ điều hợp môi trường điều phối đích khác có thể được tải về theo yêu cầu bằng npx trong lần sử dụng đầu tiên.
  • Thông tin xác thực của nhà cung cấp phải tồn tại sẵn trên máy chủ cho môi trường điều phối đó.
  • Nếu máy chủ không có npm hoặc quyền truy cập mạng, việc tải bộ điều hợp trong lần chạy đầu sẽ thất bại cho đến khi bộ nhớ đệm được làm nóng trước hoặc bộ điều hợp được cài đặt theo cách khác.
ACP khởi chạy một tiến trình môi trường điều phối bên ngoài thực sự. OpenClaw sở hữu việc đị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; môi trường điều phối sở hữu thông tin đăng nhập nhà cung cấp, danh mục mô hình, 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 cáo một backend đã bật và hoạt động bình thường.
  • Id đích được acp.allowedAgents cho phép khi danh sách cho phép đó được đặt.
  • Lệnh của môi trường điều phối có thể khởi động trên máy chủ Gateway.
  • Thông tin xác thực của nhà cung cấp hiện diện cho môi trường điều phối đó (claude, codex, gemini, opencode, droid, v.v.).
  • Mô hình đã chọn tồn tại cho môi trường điều phối đó - id mô hình không thể dùng chung giữa các môi trường điều phối.
  • cwd được yêu cầu tồn tại và có thể truy cập, hoặc bỏ qua cwd để backend dùng giá trị mặc định.
  • 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 vào lời nhắc quyền gốc, vì vậy các lượt lập trình cần nhiều thao tác ghi/thực thi thường cần hồ sơ quyền ACPX có thể tiếp tục ở chế độ không giao diện.
Theo mặc định, các công cụ Plugin OpenClaw và công cụ tích hợp sẵn của OpenClaw không được cung cấp cho các môi trường điều phối ACP. Chỉ bật các cầu nối MCP rõ ràng trong Tác nhân ACP - thiết lập khi môi trường điều phối cần gọi trực tiếp các công cụ đó.

​
Các đích môi trường điều phối được hỗ trợ

Với backend acpx, hãy dùng các id này làm đích /acp spawn <id> hoặc sessions_spawn({ runtime: "acp", agentId: "<id>" }): pi (pi-acp) cũng được đăng ký trong backend acpx nhưng không phải là một môi trường điều phối lập trình theo cùng nghĩa với các mục khác ở trên. Có thể cấu hình bí danh tác nhân acpx tùy chỉnh trong chính acpx, nhưng chính sách OpenClaw vẫn kiểm tra acp.allowedAgents và mọi ánh xạ agents.list[].runtime.acp.agent trước khi điều phối.

​
Sổ tay vận hành

Luồng /acp nhanh từ cuộc trò chuyện:
1

Khởi tạo

/acp spawn claude --bind here, /acp spawn gemini --mode persistent --thread auto hoặc /acp spawn codex --bind here rõ ràng.
2

Làm việc

Tiếp tục trong cuộc hội thoại hoặc luồng đã liên kết (hoặc chỉ định khóa phiên một cách rõ ràng).
3

Kiểm tra trạng thái

/acp status
4

Tinh chỉnh

/acp model <provider/model>, /acp permissions <profile>, /acp timeout <seconds>.
5

Điều hướng

Mà không thay thế ngữ cảnh: /acp steer tighten logging and continue.
6

Dừng

/acp cancel (lượt hiện tại) hoặc /acp close (phiên + liên kết).
  • Thao tác khởi tạo sẽ tạo mới hoặc tiếp tục một phiên runtime ACP, ghi siêu dữ liệu ACP vào kho lưu trữ phiên OpenClaw và có thể tạo một tác vụ nền khi lượt chạy thuộc quyền sở hữu của tác vụ cha.
  • Các phiên ACP thuộc quyền sở hữu của tác vụ cha được xem là công việc nền ngay cả khi phiên runtime là phiên duy trì lâu dài; việc hoàn tất và phân phối trên nhiều bề mặt đi qua trình thông báo tác vụ cha thay vì hoạt động như một phiên trò chuyện thông thường hướng đến người dùng.
  • Quá trình bảo trì tác vụ đóng các phiên ACP dùng một lần thuộc quyền sở hữu của tác vụ cha đã kết thúc hoặc bị mất liên kết. Các phiên ACP duy trì lâu dài được giữ lại khi vẫn còn liên kết hội thoại đang hoạt động; các phiên duy trì lâu dài cũ không có liên kết đang hoạt động sẽ bị đóng để không thể được âm thầm tiếp tục sau khi tác vụ sở hữu đã hoàn tất hoặc bản ghi tác vụ của nó không còn tồn tại.
  • Các tin nhắn tiếp theo đã liên kết được chuyển thẳng đến phiên ACP cho đến khi liên kết bị đóng, bỏ tiêu điểm, đặt lại hoặc hết hạn.
  • Các lệnh Gateway vẫn được xử lý cục bộ. /acp ..., /status và /unfocus không bao giờ được gửi dưới dạng văn bản lời nhắc thông thường đến một harness ACP đã liên kết.
  • cancel hủy lượt đang hoạt động khi backend hỗ trợ hủy; thao tác này không xóa liên kết hoặc siêu dữ liệu 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. Harness vẫn có thể lưu lịch sử ngược dòng của riêng nó nếu hỗ trợ tiếp tục.
  • Plugin acpx dọn dẹp các cây tiến trình trình bao bọc và bộ điều hợp do OpenClaw sở hữu sau close, đồng thời thu hồi các tiến trình ACPX mồ côi cũ do OpenClaw sở hữu trong quá trình khởi động Gateway.
  • Các worker runtime không hoạt động đủ điều kiện được dọn dẹp sau khoảng thời gian không hoạt động tích hợp sẵn; siêu dữ liệu phiên đã lưu vẫn khả dụng cho /acp sessions.
Các tác nhân kích hoạt bằng ngôn ngữ tự nhiên nên định tuyến đến Plugin Codex gốc khi Plugin này được bật:
  • “Liên kết kênh Discord này với Codex.”
  • “Gắn cuộc trò chuyện này vào luồng Codex <id>.”
  • “Hiển thị các luồng Codex, sau đó liên kết luồng này.”
Liên kết hội thoại Codex gốc là đường dẫn điều khiển trò chuyện 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 của Codex như shell/apply-patch thực thi bên trong Codex. Đối với các sự kiện công cụ gốc của Codex, OpenClaw chèn một bộ chuyển tiếp 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 các sự kiện PermissionRequest của Codex thông qua quy trình phê duyệt của OpenClaw. Các hook Stop của Codex được chuyển tiếp đến before_agent_finalize của OpenClaw, nơi các Plugin có thể yêu cầu thêm một lượt chạy mô hình trước khi Codex hoàn tất câu trả lời. Bộ chuyển tiếp được chủ ý giữ ở mức thận trọng: nó không sửa đổi các đối số công cụ gốc của Codex hoặc ghi lại bản ghi luồng Codex. Chỉ dùng ACP tường minh 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ợ Codex harness v1.
  • tham chiếu mô hình Codex cũ - tuyến mô hình đăng ký/OAuth Codex cũ được doctor sửa chữa.
  • openai/* - runtime nhúng app-server Codex gốc cho các lượt tác nhân OpenAI.
  • /codex ... - điều khiển hội thoại Codex gốc.
  • /acp ... hoặc runtime: "acp" - điều khiển ACP/acpx tường minh.
Các tác nhân kích hoạt nên định tuyến đến runtime ACP:
  • “Chạy tác vụ này dưới dạng phiên ACP Claude Code dùng 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, sau đó giữ các lượt tiếp theo trong cùng luồng đó.”
  • “Chạy Codex thông 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 chỉ định tường minh hoặc Plugin Codex gốc không khả dụng cho thao tác được yêu cầu.Đối với sessions_spawn, runtime: "acp" chỉ được công bố khi ACP được bật, bên yêu cầu không nằm trong sandbox và một backend runtime ACP đã được tải. acp.dispatch.enabled=false tạm dừng điều phối luồng ACP tự động nhưng không ẩn hoặc chặn các lệnh gọi sessions_spawn({ runtime: "acp" }) tường minh. Nó nhắm đến các id harness ACP như codex, claude, droid, gemini hoặc opencode. Không truyền id tác nhân cấu hình OpenClaw thông thường từ agents_list trừ khi mục đó được cấu hình tường minh với agents.list[].runtime.type="acp"; nếu không, hãy dùng runtime tác nhân phụ mặc định. Khi một tác nhân OpenClaw được cấu hình với runtime.type="acp", OpenClaw dùng runtime.acp.agent làm id harness nền tảng.

​
ACP so với tác nhân phụ

Dùng ACP khi bạn muốn một runtime harness bên ngoài. Dùng app-server Codex gốc để liên kết/điều khiển hội thoại Codex khi Plugin codex được bật. Dùng tác nhân phụ khi bạn muốn các lượt chạy được ủy quyền có nguồn gốc OpenClaw. Xem thêm Tác nhân phụ.

​
Cách ACP chạy Claude Code

Đối với Claude Code thông qua ACP, ngăn xếp là:
  1. Mặt phẳng điều khiển phiên ACP của OpenClaw.
  2. Plugin runtime @openclaw/acpx chính thức.
  3. Bộ điều hợp ACP Claude.
  4. Cơ chế runtime/phiên phía Claude.
ACP Claude là một phiên harness với các điều khiển ACP, khả năng tiếp tục phiên, theo dõi tác vụ nền và tùy chọn liên kết hội thoại/luồng. Các backend CLI là những runtime dự phòng cục bộ riêng biệt chỉ dùng văn bản - xem Backend CLI. Đối với người vận hành, quy tắc thực tế là:
  • Muốn /acp spawn, phiên có thể liên kết, điều khiển runtime hoặc công việc harness duy trì lâu dài? Dùng ACP.
  • Muốn cơ chế dự phòng văn bản cục bộ đơn giản thông qua CLI thô? Dùng các backend CLI.

​
Phiên đã liên kết

​
Mô hình tư duy

  • Bề mặt trò chuyện - nơi mọi người tiếp tục trò chuyện (kênh Discord, chủ đề Telegram, cuộc trò chuyện iMessage).
  • Phiên ACP - trạng thái runtime Codex/Claude/Gemini bền vững mà OpenClaw định tuyến đến.
  • Luồng/chủ đề con - một bề mặt nhắn tin bổ sung tùy chọn chỉ được tạo bởi --thread ....
  • Không gian làm việc runtime - vị trí hệ thống tệp (cwd, bản checkout kho lưu trữ, không gian làm việc backend) nơi harness chạy. Độc lập với bề mặt trò chuyện.

​
Liên kết hội thoại hiện tại

/acp spawn <harness> --bind here ghim hội thoại hiện tại vào phiên ACP đã khởi tạo - không có luồng con, vẫn cùng bề mặt trò chuyện. OpenClaw tiếp tục sở hữu phần vận chuyển, xác thực, an toàn và phân phối. Các tin nhắn tiếp theo trong hội thoại đó được định tuyến đến cùng phiên; /new và /reset đặt lại phiên tại chỗ; /acp close xóa liên kết. Ví dụ:
  • --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 rõ ràng rằng tính năng không được hỗ trợ. Liên kết vẫn 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 khởi tạo đến một tác nhân 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 nhân đích. Các đường dẫn được kế thừa bị thiếu (ENOENT/ENOTDIR) sẽ dùng mặc định của backend; các lỗi truy cập khác (ví dụ: EACCES) được hiển thị dưới dạng lỗi khởi tạo.
  • Các lệnh quản lý Gateway vẫn được xử lý cục bộ trong hội thoại đã liên kết - các lệnh /acp ... được OpenClaw xử lý ngay cả khi văn bản tiếp theo thông thường được định tuyến đến phiên ACP đã liên kết; /status và /unfocus cũng luôn được xử lý cục bộ khi việc 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ộ điều hợp kênh:
  • OpenClaw liên kết một luồng với phiên ACP đích.
  • Các tin nhắn tiếp theo trong luồng đó được định tuyến đến phiên ACP đã liên kết.
  • Đầu ra ACP được gửi trở lại cùng luồng.
  • Thao tác bỏ tiêu điểm/đóng/lưu trữ, hết thời gian chờ không hoạt động hoặc hết thời hạn tối đa sẽ xóa liên kết.
  • /acp close, /acp cancel, /acp status, /status và /unfocus là các lệnh Gateway, không phải lời nhắc cho harness ACP.
Các cờ tính năng bắt buộc cho ACP liên kết với luồng:
  • acp.enabled=true
  • acp.dispatch.enabled được bật theo mặc định (đặt false để tạm dừng điều phối luồng ACP tự động; các lệnh gọi sessions_spawn({ runtime: "acp" }) tường minh vẫn hoạt động).
  • Khả năng khởi tạo phiên luồng của bộ điều hợp kênh được bật (mặc định: true):
    • Discord: channels.discord.threadBindings.spawnSessions=true
    • Telegram: channels.telegram.threadBindings.spawnSessions=true
Hỗ trợ liên kết luồng tùy thuộc vào từng bộ điều hợp. Nếu bộ điều hợp kênh đang hoạt động không hỗ trợ liên kết luồng, OpenClaw trả về thông báo rõ ràng rằng tính năng không được hỗ trợ/không khả dụng.
  • Mọi bộ điều hợp kênh cung cấp khả năng liên kết phiên/luồng.
  • Hỗ trợ tích hợp hiện tại: các luồng/kênh Discord, các chủ đề Telegram (chủ đề diễn đàn trong nhóm/siêu nhóm và chủ đề tin nhắn trực tiếp).
  • Các kênh Plugin có thể bổ sung hỗ trợ thông qua cùng giao diện liên kết.

​
Liên kết kênh duy trì lâu dài

Đối với các quy trình không tạm thời, hãy cấu hình liên kết ACP duy trì lâu dài trong các mục bindings[] cấp cao nhất.

​
Mô hình liên kết

​
bindings[].type
"acp"
Đánh dấu một liên kết hội thoại ACP duy trì lâu dài.
​
bindings[].match
object
Xác định hội thoại đích. Cấu trúc theo từng kênh:
  • Kênh/luồng Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Kênh/tin nhắn trực tiếp Slack: match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>". Ưu tiên các ID Slack ổn định; liên kết kênh cũng khớp với các câu trả lời bên trong các luồng của kênh đó.
  • Chủ đề diễn đàn Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • Tin nhắn trực tiếp/nhóm WhatsApp: match.channel="whatsapp" + match.peer.id="<E.164|group JID>". Sử dụng số E.164 như +15555550123 cho cuộc trò chuyện trực tiếp và JID nhóm WhatsApp như 120363424282127706@g.us cho nhóm.
  • Tin nhắn trực tiếp/nhóm iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Ưu tiên chat_id:* để có liên kết nhóm ổn định.
​
bindings[].agentId
string
ID agent OpenClaw sở hữu.
​
bindings[].acp.mode
"persistent" | "oneshot"
Giá trị ghi đè ACP tùy chọn.
​
bindings[].acp.label
string
Nhãn tùy chọn dành cho người vận hành.
​
bindings[].acp.cwd
string
Thư mục làm việc thời gian chạy tùy chọn.
​
bindings[].acp.backend
string
Giá trị ghi đè backend tùy chọn.

​
Giá trị mặc định thời gian chạy cho từng agent

Sử dụng agents.list[].runtime để xác định các giá trị mặc định ACP một lần cho mỗi agent:
  • agents.list[].runtime.type="acp"
  • agents.list[].runtime.acp.agent (ID harness, ví dụ: codex hoặc claude)
  • agents.list[].runtime.acp.backend
  • agents.list[].runtime.acp.mode
  • agents.list[].runtime.acp.cwd
Thứ tự ưu tiên ghi đè cho các phiên liên kết ACP:
  1. bindings[].acp.*
  2. agents.list[].runtime.acp.*
  3. Các giá trị mặc định ACP toàn cục (ví dụ: acp.backend)

​
Ví dụ

​
Hành vi

  • OpenClaw đảm bảo phiên ACP đã cấu hình tồn tại sau bước kiểm soát quyền vào dành riêng cho kênh và trước khi sử dụng.
  • Tin nhắn trong kênh, chủ đề hoặc cuộc trò chuyện đó được định tuyến đến phiên ACP đã cấu hình.
  • Các liên kết ACP đã cấu hình sở hữu tuyến phiên của chúng. Phân phối dạng broadcast đến nhiều đích của kênh không thay thế phiên ACP đã cấu hình đối với một liên kết khớp.
  • Trong các cuộc trò chuyện đã liên kết, /new và /reset đặt lại cùng một khóa phiên ACP tại chỗ.
  • Các liên kết thời gian chạy tạm thời (ví dụ: được tạo bởi luồng tập trung vào luồng hội thoại) vẫn áp dụng khi có.
  • Đối với việc khởi tạo ACP giữa các agent mà không có cwd tường minh, OpenClaw kế thừa không gian làm việc của agent đích từ cấu hình agent.
  • Các đường dẫn không gian làm việc được kế thừa nhưng không tồn tại sẽ dùng cwd mặc định của backend; lỗi truy cập đối với đường dẫn có tồn tại được trả về dưới dạng lỗi khởi tạo.

​
Khởi động phiên ACP

Có hai cách để khởi động một phiên ACP:
Sử dụng runtime: "acp" để khởi động một phiên ACP từ một lượt xử lý của agent hoặc một lệnh gọi công cụ.
runtime mặc định là subagent, vì vậy hãy đặt runtime: "acp" tường minh cho các phiên ACP. Nếu bỏ qua agentId, OpenClaw sử dụng acp.defaultAgent khi được cấu hình. mode: "session" yêu cầu thread: true để duy trì một cuộc trò chuyện liên kết lâu dài.

​
Tham số sessions_spawn

​
task
string
bắt buộc
Lời nhắc ban đầu được gửi đến phiên ACP.
​
runtime
"acp"
bắt buộc
Phải là "acp" đối với các phiên ACP.
​
agentId
string
ID harness đích của ACP. Dùng acp.defaultAgent làm phương án dự phòng nếu được đặt.
​
thread
boolean
mặc định:"false"
Yêu cầu luồng liên kết luồng hội thoại ở nơi được hỗ trợ.
​
mode
"run" | "session"
mặc định:"run"
"run" chạy một lần; "session" là lâu dài. Nếu thread: true và bỏ qua mode, OpenClaw có thể mặc định sử dụng hành vi lâu dài tùy theo đường dẫn thời gian chạy. mode: "session" yêu cầu thread: true.
​
cwd
string
Thư mục làm việc thời gian chạy được yêu cầu (được xác thực theo chính sách backend/thời gian chạy). Nếu bỏ qua, thao tác khởi tạo ACP kế thừa không gian làm việc của agent đích khi được cấu hình; các đường dẫn được kế thừa nhưng không tồn tại sẽ dùng giá trị mặc định của backend, còn lỗi truy cập thực tế sẽ được trả về.
​
label
string
Nhãn dành cho người vận hành, được sử dụng trong văn bản phiên/biểu ngữ.
​
resumeSessionId
string
Tiếp tục một phiên ACP hiện có thay vì tạo phiên mới. Agent phát lại lịch sử trò chuyện của phiên qua session/load. Yêu cầu runtime: "acp".
​
streamTo
"parent"
"parent" truyền phát các bản tóm tắt tiến trình chạy ACP ban đầu trở lại phiên yêu cầu dưới dạng sự kiện hệ thống. OpenClaw ghi lại toàn bộ lịch sử chuyển tiếp trong trạng thái SQLite của agent con và xóa lịch sử đó cùng với phiên con. Theo mặc định, luồng tiến trình của phiên cha hiển thị phần bình luận của trợ lý và tiến trình trạng thái ACP, trừ khi streaming.progress.commentary=false. Discord cũng mặc định đặt bản xem trước của phiên cha ở chế độ tiến trình khi chưa cấu hình chế độ truyền phát. Tiến trình trạng thái vẫn tuân theo acp.stream.tagVisibility, vì vậy các thẻ như plan vẫn bị ẩn trừ khi được bật tường minh.
Các lượt chạy ACP sessions_spawn sử dụng agents.defaults.subagents.runTimeoutSeconds làm giới hạn lượt con mặc định. Công cụ không chấp nhận giá trị ghi đè thời gian chờ theo từng lệnh gọi (runTimeoutSeconds/timeoutSeconds bị từ chối kèm lỗi yêu cầu cấu hình giá trị mặc định).
​
model
string
Giá trị ghi đè mô hình tường minh cho phiên ACP con. Các thao tác khởi tạo Codex ACP chuẩn hóa các tham chiếu OpenAI như openai/gpt-5.4 thành cấu hình khởi động Codex ACP trước session/new; các dạng có dấu gạch chéo như openai/gpt-5.4/high cũng đặt mức độ suy luận của Codex ACP. Khi bỏ qua, sessions_spawn({ runtime: "acp" }) sử dụng các giá trị mặc định hiện có về mô hình subagent (agents.defaults.subagents.model hoặc agents.list[].subagents.model) khi được cấu hình; nếu không, nó cho phép harness ACP sử dụng mô hình mặc định riêng. Các harness khác phải công bố ACP models và hỗ trợ session/set_model; nếu không, OpenClaw/acpx sẽ báo lỗi rõ ràng thay vì âm thầm dùng mô hình mặc định của agent đích.
​
thinking
string
Mức độ tư duy/suy luận tường minh. Đối với Codex ACP, minimal ánh xạ thành mức thấp, low/medium/high/xhigh ánh xạ trực tiếp, còn off bỏ qua giá trị ghi đè mức độ suy luận khi khởi động. Khi bỏ qua, các thao tác khởi tạo ACP sử dụng các giá trị mặc định hiện có về tư duy của subagent và agents.defaults.models["provider/model"].params.thinking theo từng mô hình cho mô hình đã chọn.

​
Chế độ liên kết và luồng hội thoại khi khởi tạo

Ghi chú:
  • --bind here là cách đơn giản nhất để người vận hành “dùng Codex làm backend cho kênh hoặc cuộc trò chuyện này”.
  • --bind here không tạo luồng hội thoại con.
  • --bind here chỉ khả dụng trên các kênh cung cấp khả năng liên kết cuộc trò chuyện hiện tại.
  • Không thể kết hợp --bind và --thread trong cùng một lệnh gọi /acp spawn.

​
Mô hình phân phối

Các phiên ACP có thể là không gian làm việc tương tác hoặc công việc nền do phiên cha sở hữu. Đường dẫn phân phối phụ thuộc vào dạng đó.
Các phiên tương tác được thiết kế để tiếp tục trò chuyện trên một bề mặt trò chuyện hiển thị:
  • /acp spawn ... --bind here liên kết cuộc trò chuyện hiện tại với phiên ACP.
  • /acp spawn ... --thread ... liên kết một luồng/chủ đề của kênh với phiên ACP.
  • bindings[].type="acp" được cấu hình lâu dài định tuyến các cuộc trò chuyện khớp đến cùng một phiên ACP.
Các tin nhắn tiếp theo trong cuộc trò chuyện đã liên kết được định tuyến trực tiếp đến phiên ACP, và đầu ra ACP được phân phối trở lại cùng kênh/luồng/chủ đề đó.Nội dung OpenClaw gửi đến harness:
  • Các lượt theo dõi liên kết thông thường được gửi dưới dạng văn bản lời nhắc, kèm tệp đính kèm chỉ khi bộ kiểm thử/backend hỗ trợ.
  • Các lệnh quản lý /acp và lệnh Gateway cục bộ được chặn trước khi điều phối ACP.
  • Các sự kiện hoàn tất do runtime tạo ra được hiện thực hóa theo từng đích. Các agent OpenClaw nhận phong bì ngữ cảnh runtime nội bộ của OpenClaw; các bộ kiểm thử ACP bên ngoài nhận lời nhắc thuần túy chứa kết quả của tiến trình con và chỉ dẫn. Không bao giờ được gửi phong bì <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> thô tới các bộ kiểm thử bên ngoài hoặc lưu nó dưới dạng văn bản bản ghi người dùng ACP.
  • Các mục bản ghi ACP sử dụng văn bản kích hoạt hiển thị cho người dùng hoặc lời nhắc hoàn tất thuần túy. Siêu dữ liệu sự kiện nội bộ vẫn được giữ ở dạng có cấu trúc trong OpenClaw khi có thể và không được coi là nội dung trò chuyện do người dùng soạn.
Các phiên ACP một lần được tạo bởi một lượt chạy agent khác là các tiến trình con chạy nền, tương tự như các agent con:
  • Tiến trình cha yêu cầu thực hiện công việc bằng sessions_spawn({ runtime: "acp", mode: "run" }).
  • Tiến trình con chạy trong phiên bộ kiểm thử ACP riêng.
  • Các lượt của tiến trình con chạy trên cùng làn nền được các lần tạo agent con gốc sử dụng, vì vậy một bộ kiểm thử ACP chậm không chặn công việc không liên quan trong phiên chính.
  • Báo cáo hoàn tất được gửi lại qua đường dẫn thông báo hoàn tất tác vụ. OpenClaw chuyển đổi siêu dữ liệu hoàn tất nội bộ thành lời nhắc ACP thuần túy trước khi gửi tới bộ kiểm thử bên ngoài, vì vậy các bộ kiểm thử không thấy các dấu ngữ cảnh runtime chỉ dành cho OpenClaw.
  • Tiến trình cha viết lại kết quả của tiến trình con bằng giọng trợ lý thông thường khi cần phản hồi hiển thị cho người dùng.
Không coi đường dẫn này là cuộc trò chuyện ngang hàng giữa tiến trình cha và tiến trình con. Tiến trình con đã có một kênh hoàn tất để gửi lại cho tiến trình cha.
sessions_send có thể nhắm tới một phiên khác sau khi tạo. Đối với các phiên ngang hàng thông thường, OpenClaw sử dụng đường dẫn theo dõi agent-tới-agent (A2A) sau khi chèn thông điệp:
  • Chờ phản hồi của phiên đích.
  • Tùy chọn cho phép bên yêu cầu và đích trao đổi một số lượng hữu hạn các lượt theo dõi.
  • Yêu cầu đích tạo thông điệp thông báo.
  • Phân phối thông báo đó tới kênh hoặc luồng hiển thị.
Đường dẫn A2A đó là phương án dự phòng cho các lượt gửi ngang hàng khi bên gửi cần một lượt theo dõi hiển thị. Nó vẫn được bật khi một phiên không liên quan có thể thấy và gửi thông điệp đến đích ACP, ví dụ trong các cài đặt tools.sessions.visibility rộng.OpenClaw chỉ bỏ qua lượt theo dõi A2A khi bên yêu cầu là tiến trình cha của chính tiến trình con ACP một lần do tiến trình cha sở hữu. Trong trường hợp đó, việc chạy A2A chồng lên quá trình hoàn tất tác vụ có thể đánh thức tiến trình cha bằng kết quả của tiến trình con, chuyển tiếp phản hồi của tiến trình cha trở lại tiến trình con và tạo vòng lặp vọng lại giữa tiến trình cha/tiến trình con. Kết quả sessions_send báo cáo delivery.status="skipped" cho trường hợp tiến trình con được sở hữu đó vì đường dẫn hoàn tất đã chịu trách nhiệm về kết quả.
Sử 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ử hội thoại qua session/load, nhờ đó tiếp tục với đầy đủ ngữ cảnh trước đó.
Các trường hợp sử dụng phổ biến:
  • Chuyển giao một phiên Codex từ máy tính xách tay sang điện thoại - yêu cầu agent tiếp tục từ chỗ bạn đã dừng.
  • Tiếp tục một phiên lập trình mà bạn đã bắt đầu tương tác trong CLI, giờ đây chạy không giao diện thông qua agent.
  • Tiếp tục công việc bị gián đoạn do Gateway khởi động lại hoặc hết thời gian chờ khi không hoạt động.
Lưu ý:
  • resumeSessionId chỉ áp dụng khi runtime: "acp"; runtime agent con mặc định bỏ qua trường chỉ dành cho ACP này.
  • streamTo chỉ áp dụng khi runtime: "acp"; runtime agent con mặc định bỏ qua trường chỉ dành cho ACP này.
  • resumeSessionId là mã tiếp tục ACP/bộ kiểm thử cục bộ trên máy chủ, không phải khóa phiên kênh OpenClaw; OpenClaw vẫn kiểm tra chính sách tạo ACP và chính sách agent đích trước khi điều phối, còn backend ACP hoặc bộ kiểm thử chịu trách nhiệm cấp quyền để tải mã nguồn ngược đó.
  • resumeSessionId khôi phục lịch sử hội thoại ACP nguồn ngược; thread và mode vẫn áp dụng bình thường cho phiên OpenClaw mới mà bạn đang tạo, vì vậy mode: "session" vẫn yêu cầu thread: true.
  • Agent đích phải hỗ trợ session/load (Codex và Claude Code đều hỗ trợ).
  • Nếu không tìm thấy mã phiên, thao tác tạo sẽ thất bại với lỗi rõ ràng - không âm thầm chuyển sang phiên mới.
Sau khi triển khai Gateway, hãy chạy kiểm tra trực tiếp từ đầu đến cuối thay vì tin tưởng các kiểm thử đơn vị:
  1. Xác minh phiên bản và commit của Gateway đã triển khai trên máy chủ đích.
  2. Mở một phiên cầu nối ACPX tạm thời tới một agent trực tiếp.
  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 trình xác thực.
  5. Dọn dẹp phiên cầu nối tạm thời.
Giữ cổng kiểm soát trên mode: "run" và bỏ qua streamTo: "parent" - mode: "session" liên kết với luồng và các đường dẫn chuyển tiếp luồng là những lượt tích hợp phong phú hơn riêng biệt.

​
Khả năng tương thích với sandbox

Các phiên ACP hiện chạy trên runtime máy chủ, không chạy bên trong sandbox OpenClaw.
Ranh giới bảo mật:
  • Bộ kiểm thử bên ngoài có thể đọc/ghi theo quyền CLI riêng và cwd đã chọn.
  • Chính sách sandbox của OpenClaw không bao bọc việc thực thi bộ kiểm thử ACP.
  • OpenClaw vẫn thực thi các cổng tính năng ACP, agent được phép, quyền sở hữu phiên, liên kết kênh và chính sách phân phối Gateway.
  • Sử dụng runtime: "subagent" cho công việc gốc OpenClaw được sandbox thực thi.
Các hạn chế hiện tại:
  • Nếu phiên yêu cầu được sandbox, việc tạo ACP bị chặn cho cả sessions_spawn({ runtime: "acp" }) và /acp spawn.
  • sessions_spawn với runtime: "acp" không hỗ trợ sandbox: "require".

​
Phân giải đích phiên

Hầu hết hành động /acp chấp nhận một đích phiên tùy chọn (session-key, session-id hoặc session-label). Thứ tự phân giải:
  1. Đối số đích tường minh (hoặc --session cho /acp steer)
    • thử khóa
    • sau đó là mã phiên có dạng UUID
    • sau đó là nhãn
  2. Liên kết luồng hiện tại (nếu cuộc hội thoại/luồng này được liên kết với một phiên ACP).
  3. Phương án dự phòng là phiên của bên yêu cầu hiện tại.
Cả liên kết cuộc hội thoại hiện tại và liên kết luồng đều tham gia bước 2. Nếu không phân giải được đích nào, OpenClaw trả về lỗi rõ ràng (Unable to resolve session target: ...).

​
Các điều khiển ACP

Các điều khiển runtime (spawn, cancel, steer, close, status, set-mode, set, cwd, permissions, timeout, model và reset-options) yêu cầu danh tính chủ sở hữu từ các kênh bên ngoài và operator.admin từ các máy khách Gateway nội bộ. Bên gửi không phải chủ sở hữu nhưng được cấp quyền vẫn có thể sử dụng sessions, doctor, install và help. Đối với bên gửi không phải chủ sở hữu, /acp sessions chỉ liệt kê phiên đang được liên kết hoặc phiên của bên yêu cầu; danh tính chủ sở hữu và máy khách operator.admin thấy tất cả các phiên gần đây. /acp status hiển thị các tùy chọn runtime có hiệu lực cùng các mã định danh phiên cấp runtime và cấp backend. Lỗi điều khiển không được hỗ trợ được hiển thị rõ ràng khi backend thiếu một khả năng. Các lệnh chấp nhận token đích (session-key, session-id hoặc session-label) phân giải chúng thông qua cơ chế khám phá phiên của Gateway, bao gồm các gốc session.store tùy chỉnh theo từng agent. /acp sessions không chấp nhận token đích.

​
Ánh xạ tùy chọn runtime

/acp có các lệnh tiện ích và một trình đặt chung. Các thao tác tương đương:

​
Harness acpx, thiết lập plugin và quyền

Để biết cấu hình harness acpx (các bí danh Claude Code / Codex / Gemini CLI), các cầu nối MCP plugin-tools và OpenClaw-tools cũng như các chế độ quyền ACP, hãy xem Tác nhân ACP - thiết lập.

​
Khắc phục sự cố

Command blocked by PreToolUse hook: Native hook relay unavailable thuộc về cơ chế chuyển tiếp hook Codex gốc, không phải ACP/acpx. Trong một cuộc trò chuyện Codex đã liên kết, hãy bắt đầu phiên mới bằng /new hoặc /reset; nếu thao tác này hoạt động một lần rồi lỗi quay lại trong lần gọi công cụ gốc tiếp theo, hãy khởi động lại app-server Codex hoặc OpenClaw Gateway thay vì lặp lại /new. Xem Khắc phục sự cố harness Codex.

​
Liên quan