Phiên Agent Client Protocol (ACP) cho phép OpenClaw chạy các harness lập trình bên ngoài (ví dụ Pi, Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI, và các harness ACPX được hỗ trợ khác) thông qua một Plugin backend ACP. Mỗi lần tạo phiên ACP đều được theo dõi dưới dạng một tác vụ nền.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
ACP là đường dẫn harness bên ngoài, không phải đường dẫn Codex mặc định. Plugin
máy chủ ứng dụng Codex gốc sở hữu các điều khiển
/codex ... và runtime nhúng
agentRuntime.id: "codex"; ACP sở hữu các điều khiển
/acp ... và các phiên sessions_spawn({ runtime: "acp" }).Nếu bạn muốn Codex hoặc Claude Code kết nối trực tiếp như một MCP client bên ngoài
vào các cuộc hội thoại kênh OpenClaw hiện có, hãy dùng
openclaw mcp serve thay vì ACP.Tôi cần trang nào?
| Bạn muốn… | Dùng mục này | Ghi chú |
|---|---|---|
| Liên kết hoặc điều khiển Codex trong cuộc hội thoại hiện tại | /codex bind, /codex threads | Đường dẫn máy chủ ứng dụng Codex gốc khi Plugin codex được bật; bao gồm trả lời chat đã liên kết, chuyển tiếp hình ảnh, model/nhanh/quyền, dừng và điều khiển định hướng. ACP là phương án dự phòng rõ ràng |
| Chạy Claude Code, Gemini CLI, Codex ACP rõ ràng, hoặc một harness bên ngoài khác thông qua OpenClaw | Trang này | Các phiên gắn với chat, /acp spawn, sessions_spawn({ runtime: "acp" }), tác vụ nền, điều khiển runtime |
| Phơi bày một phiên OpenClaw Gateway dưới dạng máy chủ ACP cho editor hoặc client | openclaw acp | Chế độ cầu nối. IDE/client giao tiếp ACP với OpenClaw qua stdio/WebSocket |
| Tái sử dụng một AI CLI cục bộ làm model dự phòng chỉ văn bản | Backend CLI | Không phải ACP. Không có công cụ OpenClaw, không có điều khiển ACP, không có runtime harness |
Cái này có hoạt động ngay không?
Thường là có. Các bản cài đặt mới đi kèm Plugin runtimeacpx tích hợp được bật
theo mặc định, với binary acpx được ghim cục bộ theo Plugin mà OpenClaw thăm dò
và tự sửa khi khởi động. Chạy /acp doctor để kiểm tra mức sẵn sàng.
OpenClaw chỉ dạy agent về việc tạo phiên ACP khi ACP thực sự
có thể dùng: ACP phải được bật, dispatch không được bị tắt, phiên hiện tại
không được bị sandbox chặn, và một backend runtime phải được tải. Nếu các điều kiện
đó không được đáp ứng, Skills Plugin ACP và hướng dẫn ACP cho
sessions_spawn vẫn bị ẩn để agent không đề xuất một backend không khả dụng.
Những điều dễ vướng khi chạy lần đầu
Những điều dễ vướng khi chạy lần đầu
- Nếu
plugins.allowđược đặt, đó là danh mục Plugin giới hạn và phải bao gồmacpx; nếu không, mặc định tích hợp sẽ bị chặn có chủ ý và/acp doctorbáo mục allowlist bị thiếu. - Adapter Codex ACP tích hợp được chuẩn bị cùng Plugin
acpxvà đượ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
npxtrong 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 theo cách khác.
Điều kiện tiên quyết của runtime
Điều kiện tiên quyết của runtime
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, danh mục model, hành vi hệ thống tệp và
công cụ gốc của nó.Trước khi quy lỗi cho OpenClaw, hãy xác minh:
/acp doctorbáo một backend đã bật và khỏe mạnh.- Id đích được
acp.allowedAgentscho 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 có mặt cho harness đó (
claude,codex,gemini,opencode,droid, v.v.). - Model đã chọn tồn tại cho harness đó — các id model không thể dùng thay thế giữa các harness.
cwdđược yêu cầu tồn tại và có thể truy cập, hoặc bỏ quacwdvà để backend dùng mặc định của nó.- Chế độ quyền khớp với công việc. Các phiên không tương tác không thể bấm 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.
Mục tiêu harness được hỗ trợ
Với backendacpx tích hợp, hãy dùng các id harness này làm mục tiêu /acp spawn <id>
hoặc sessions_spawn({ runtime: "acp", agentId: "<id>" }):
| Id harness | Backend điển hình | Ghi chú |
|---|---|---|
claude | Adapter Claude Code ACP | Yêu cầu xác thực Claude Code trên host. |
codex | Adapter Codex ACP | Chỉ là phương án dự phòng ACP rõ ràng khi /codex gốc không khả dụng hoặc ACP được yêu cầu. |
copilot | Adapter GitHub Copilot ACP | Yêu cầu xác thực Copilot CLI/runtime. |
cursor | Cursor CLI ACP (cursor-agent acp) | Ghi đè lệnh acpx nếu bản cài cục bộ phơi bày entrypoint ACP khác. |
droid | Factory Droid CLI | Yêu cầu xác thực Factory/Droid hoặc FACTORY_API_KEY trong môi trường harness. |
gemini | Adapter Gemini CLI ACP | Yêu cầu xác thực Gemini CLI hoặc thiết lập khóa API. |
iflow | iFlow CLI | Tính khả dụng của adapter và điều khiển model phụ thuộc vào CLI đã cài. |
kilocode | Kilo Code CLI | Tính khả dụng của adapter và điều khiển model phụ thuộc vào CLI đã cài. |
kimi | Kimi/Moonshot CLI | Yêu cầu xác thực Kimi/Moonshot trên host. |
kiro | Kiro CLI | Tính khả dụng của adapter và điều khiển model phụ thuộc vào CLI đã cài. |
opencode | Adapter OpenCode ACP | Yêu cầu xác thực OpenCode CLI/nhà cung cấp. |
openclaw | Cầu nối OpenClaw Gateway qua openclaw acp | Cho phép một harness hỗ trợ ACP giao tiếp ngược với một phiên OpenClaw Gateway. |
pi | Runtime OpenClaw nhúng/Pi | Dùng cho các thử nghiệm harness gốc OpenClaw. |
qwen | Qwen Code / Qwen CLI | Yêu cầu xác thực tương thích Qwen trên host. |
acp.allowedAgents và mọi ánh xạ
agents.list[].runtime.acp.agent trước khi dispatch.
Runbook cho operator
Luồng/acp nhanh từ chat:
Tạo phiên
/acp spawn claude --bind here,
/acp spawn gemini --mode persistent --thread auto, hoặc rõ ràng
/acp spawn codex --bind here.Chi tiết vòng đời
Chi tiết vòng đời
- Tạo phiên sẽ tạo mới 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 một 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 xem là công việc nền ngay cả khi phiên runtime là persistent; hoàn tất và phân phối liê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 thông thường hướng người dù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 khi vẫn còn liên kết hội thoại đang hoạt động; các phiên persistent cũ không có liên kết đang hoạt động sẽ 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 trực tiếp 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.
- Lệnh Gateway vẫn cục bộ.
/acp ...,/status, và/unfocuskhông bao giờ được gửi như văn bản prompt thông thường tới harness ACP đã liên kết. cancelhủy lượt đang hoạt động khi backend hỗ trợ hủy; nó không xóa liên kết hoặc metadata phiên.closekế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 riêng nếu nó 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 khả dụng cho/acp sessions.
Quy tắc định tuyến Codex gốc
Quy tắc định tuyến Codex gốc
Các trigger ngôn ngữ tự nhiên nên được định tuyến tới Plugin Codex
gốc khi Plugin đó được bật:
- “Liên kết kênh Discord này với Codex.”
- “Gắn chat này với thread Codex
<id>.” - “Hiển thị các thread Codex, rồi liên kết thread này.”
before_tool_call, quan sát
after_tool_call, và định tuyến các sự kiện Codex PermissionRequest
thông qua phê duyệt OpenClaw. Các hook Codex Stop được relay tới
OpenClaw before_agent_finalize, nơi các 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 vẫn
cố ý thận trọng: 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.Bảng tham chiếu nhanh chọn mô hình / nhà cung cấp / runtime
Bảng tham chiếu nhanh chọn mô hình / nhà cung cấp / runtime
openai-codex/*— tuyến OAuth/gói đăng ký PI Codex.openai/*cộng vớiagentRuntime.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ặcruntime: "acp"— điều khiển ACP/acpx tường minh.
Tác nhân kích hoạt ngôn ngữ tự nhiên định tuyến ACP
Tác nhân kích hoạt ngôn ngữ tự nhiên định tuyến ACP
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 một phiên Claude Code ACP một lần rồi 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 theo dõi trong cùng luồng đó.”
- “Chạy Codex qua ACP trong một luồng nề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 theo dõi đế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.Với sessions_spawn, runtime: "acp" chỉ được quả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 đ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 agent
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 sub-agent mặc định. Khi một agent 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.ACP so với sub-agent
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 Plugincodex
được bật. Dùng sub-agent khi bạn muốn các lượt chạy được ủy quyền
gốc OpenClaw.
| Khu vực | Phiên ACP | Lượt chạy sub-agent |
|---|---|---|
| Runtime | Plugin backend ACP (ví dụ acpx) | Runtime sub-agent gốc OpenClaw |
| Khóa phiên | agent:<agentId>:acp:<uuid> | agent:<agentId>:subagent:<uuid> |
| Lệnh chính | /acp ... | /subagents ... |
| Công cụ tạo | sessions_spawn với runtime:"acp" | sessions_spawn (runtime mặc định) |
Cách ACP chạy Claude Code
Với Claude Code qua ACP, ngăn xếp là:- Mặt phẳng điều khiển phiên ACP của OpenClaw.
- Plugin runtime
acpxđi kèm. - Bộ chuyển đổi ACP của Claude.
- Cơ chế runtime/phiên phía Claude.
- Muốn
/acp spawn, phiên có thể liên kết, điều khiển runtime, hoặc công việc harness bền vững? Dùng ACP. - Muốn dự phòng văn bản cục bộ đơn giản qua CLI thô? Dùng backend CLI.
Phiên đã liên kết
Mô hình tư duy
- Bề mặt chat — nơi mọi người tiếp tục trò chuyện (kênh Discord, chủ đề Telegram, chat iMessage).
- Phiên ACP — trạng thái runtime Codex/Claude/Gemini bền vững mà OpenClaw định tuyến tới.
- Luồng/chủ đề con — 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, checkout repo, không gian làm việc backend) nơi harness chạy. Độc lập với bề mặt chat.
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 đã tạo — không có luồng con, cùng bề mặt chat. OpenClaw tiếp tục
sở hữu transport, xác thực, an toàn và phân phối. Các tin nhắn theo dõi 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 gỡ liên kết.
Ví dụ:
Quy tắc liên kết và tính loại trừ
Quy tắc liên kết và tính loại trừ
--bind herevà--thread ...loại trừ lẫn nhau.--bind herechỉ hoạt động trên các kênh quảng bá khả năng liên kết hội thoại hiện tại; nếu không, OpenClaw trả về một thông báo không được hỗ trợ rõ ràng. Liên kết tồn tại qua các lần khởi động lại Gateway.- Trên Discord,
spawnAcpSessionschỉ bắt buộc khi OpenClaw cần tạo luồng con cho--thread auto|here— không áp dụng cho--bind here. - Nếu bạn tạo phiên cho một agent 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 agent đích. Đường dẫn kế thừa bị thiếu (ENOENT/ENOTDIR) sẽ quay về mặc định backend; các lỗi truy cập khác (ví dụEACCES) xuất hiện dưới dạng lỗi tạo phiên. - Các lệnh quản lý Gateway vẫn cục bộ trong hội thoại đã liên kết — lệnh
/acp ...được OpenClaw xử lý ngay cả khi văn bản theo dõi thông thường định tuyến đến phiên ACP đã liên kết;/statusvà/unfocuscũng vẫn cục bộ bất cứ khi nào xử lý lệnh được bật cho bề mặt đó.
Phiên liên kết theo luồng
Phiên liên kết theo luồng
Khi liên kết luồng được bật cho bộ chuyển đổi kênh:
- OpenClaw liên kết một luồng với phiên ACP đích.
- Tin nhắn theo dõi trong luồng đó định tuyến đến phiên ACP đã liên kết.
- Đầu ra ACP được phân phối trở lại cùng luồng.
- Unfocus/đóng/lưu trữ/hết thời gian nhàn rỗi hoặc hết hạn tuổi tối đa sẽ gỡ liên kết.
/acp close,/acp cancel,/acp status,/status, và/unfocuslà các lệnh Gateway, không phải prompt gửi đến harness ACP.
acp.enabled=trueacp.dispatch.enabledđược bật theo mặc định (đặtfalseđể tạm dừng điều phối luồng ACP tự động; các lệnh gọisessions_spawn({ runtime: "acp" })tường minh vẫn hoạt động).- Cờ tạo luồng ACP của bộ chuyển đổi kênh được bật (tùy bộ chuyển đổi):
- Discord:
channels.discord.threadBindings.spawnAcpSessions=true - Telegram:
channels.telegram.threadBindings.spawnAcpSessions=true
- Discord:
Kênh hỗ trợ luồng
Kênh hỗ trợ luồng
- Bất kỳ bộ chuyển đổi kênh nào cung cấp 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).
- Kênh Plugin có thể thêm hỗ trợ thông qua cùng giao diện liên kết.
Liên kết kênh bền vững
Với các quy trình làm việc không tạm thời, hãy cấu hình liên kết ACP bền vững trong các mụcbindings[] cấp cao nhất.
Mô hình liên kết
Đánh dấu một liên kết hội thoại ACP bền vững.
Xác định hội thoại đích. Các dạng theo từng kênh:
- Kênh/luồng Discord:
match.channel="discord"+match.peer.id="<channelOrThreadId>" - Chủ đề diễn đàn Telegram:
match.channel="telegram"+match.peer.id="<chatId>:topic:<topicId>" - DM/nhóm BlueBubbles:
match.channel="bluebubbles"+match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Ưu tiênchat_id:*hoặcchat_identifier:*cho liên kết nhóm ổn định. - DM/nhóm iMessage:
match.channel="imessage"+match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Ưu tiênchat_id:*cho liên kết nhóm ổn định.
Id agent OpenClaw sở hữu.
Ghi đè ACP tùy chọn.
Nhãn tùy chọn dành cho người vận hành.
Thư mục làm việc runtime tùy chọn.
Ghi đè backend tùy chọn.
Mặc định runtime theo agent
Dùngagents.list[].runtime để định nghĩa 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ụcodexhoặcclaude)agents.list[].runtime.acp.backendagents.list[].runtime.acp.modeagents.list[].runtime.acp.cwd
bindings[].acp.*agents.list[].runtime.acp.*- 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 trước khi sử dụng.
- Tin nhắn trong kênh hoặc chủ đề đó định tuyến đến phiên ACP đã cấu hình.
- Trong hội thoại đã liên kết,
/newvà/resetđặt lại cùng khóa phiên ACP tại chỗ. - Liên kết runtime tạm thời (ví dụ do luồng tập trung theo luồng tạo ra) vẫn áp dụng ở nơi hiện diện.
- Với các lần tạo ACP xuyên agent không có
cwdtường minh, OpenClaw kế thừa không gian làm việc agent đích từ cấu hình agent. - Đường dẫn không gian làm việc kế thừa bị thiếu sẽ quay về cwd mặc định của backend; lỗi truy cập không phải do thiếu sẽ xuất hiện dưới dạng lỗi tạo phiên.
Khởi động phiên ACP
Hai cách để khởi động một phiên ACP:- Từ sessions_spawn
- Từ lệnh /acp
Dùng
runtime: "acp" để khởi động một phiên ACP từ lượt của agent hoặc
lệnh gọi công cụ.runtime mặc định là subagent, vì vậy hãy đặt rõ runtime: "acp"
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 để giữ một cuộc trò chuyện đã liên kết bền vững.Tham số sessions_spawn
Lời nhắc ban đầu được gửi đến phiên ACP.
Phải là
"acp" cho các phiên ACP.ID bộ điều phối đích ACP. Quay về
acp.defaultAgent nếu đã đặt.Yêu cầu luồng liên kết luồng khi được hỗ trợ.
"run" là một lần; "session" là bền vững. Nếu thread: true và
bỏ qua mode, OpenClaw có thể mặc định dùng hành vi bền vững theo
đường dẫn môi trường chạy. mode: "session" yêu cầu thread: true.Thư mục làm việc môi trường chạy được yêu cầu (được xác thực bởi chính sách
phần phụ trợ/môi trường chạy). Nếu bỏ qua, thao tác sinh ACP kế thừa không gian làm việc
của tác nhân đích khi đã được cấu hình; các đường dẫn kế thừa bị thiếu sẽ quay về
mặc định phần phụ trợ, còn lỗi truy cập thực sẽ được trả về.
Nhãn hiển thị cho người vận hành được dùng trong văn bản phiên/biểu ngữ.
Tiếp tục một phiên ACP hiện có thay vì tạo phiên mới. Tác nhân
phát lại lịch sử cuộc trò chuyện của nó qua
session/load. Yêu cầu
runtime: "acp"."parent" truyền các bản tóm tắt tiến trình lần chạy ACP ban đầu về
phiên yêu cầu dưới dạng sự kiện hệ thống. Phản hồi được chấp nhận bao gồm
streamLogPath trỏ đến nhật ký JSONL trong phạm vi phiên
(<sessionId>.acp-stream.jsonl) mà bạn có thể theo dõi để xem đầy đủ lịch sử chuyển tiếp.Hủy lượt ACP con sau N giây.
0 giữ lượt trên đường dẫn không hết thời gian chờ
của Gateway. Cùng một giá trị được áp dụng cho lần chạy Gateway
và môi trường chạy ACP để các bộ điều phối bị kẹt/hết hạn mức không
chiếm làn tác nhân cha vô thời hạn.Ghi đè mô hình rõ ràng cho phiên ACP con. Các lần sinh Codex ACP
chuẩn hóa các tham chiếu OpenClaw Codex như
openai-codex/gpt-5.4 thành cấu hình
khởi động Codex ACP trước session/new; các dạng gạch chéo như
openai-codex/gpt-5.4/high cũng đặt mức nỗ lực suy luận Codex ACP.
Các bộ điều phối khác phải quảng bá ACP models và hỗ trợ
session/set_model; nếu không OpenClaw/acpx sẽ lỗi rõ ràng thay vì
âm thầm quay về mặc định tác nhân đích.Mức nỗ lực suy nghĩ/suy luận rõ ràng. Với Codex ACP,
minimal ánh xạ đến
mức nỗ lực thấp, low/medium/high/xhigh ánh xạ trực tiếp, và off
bỏ qua ghi đè khởi động mức nỗ lực suy luận.Chế độ liên kết sinh và luồng
- --bind here|off
- --thread auto|here|off
| Chế độ | Hành vi |
|---|---|
here | Liên kết cuộc trò chuyện đang hoạt động hiện tại tại chỗ; lỗi nếu không có cuộc trò chuyện nào hoạt động. |
off | Không tạo liên kết cuộc trò chuyện hiện tại. |
--bind herelà đường dẫn người vận hành đơn giản nhất để “biến kênh hoặc cuộc trò chuyện này thành được Codex hỗ trợ.”--bind herekhông tạo luồng con.--bind herechỉ khả dụng trên các kênh cung cấp hỗ trợ liên kết cuộc trò chuyện hiện tại.- Không thể kết hợp
--bindvà--threadtrong cùng một lần 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 hình dạng đó.Phiên ACP tương tác
Phiên ACP tương tác
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 hereliê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ủ đề kênh với phiên ACP.bindings[].type="acp"được cấu hình bền vững định tuyến các cuộc trò chuyện khớp đến cùng một phiên ACP.
- Các lượt tiếp theo đã liên kết thông thường được gửi dưới dạng văn bản lời nhắc, cộng với tệp đính kèm chỉ khi bộ điều phối/phần phụ trợ hỗ trợ chúng.
- Các lệnh quản lý
/acpvà lệnh Gateway cục bộ bị chặn trước khi điều phối ACP. - Các sự kiện hoàn tất do môi trường chạy tạo được hiện thực hóa theo từng đích. Tác nhân OpenClaw nhận phong bì ngữ cảnh môi trường chạy nội bộ của OpenClaw; các bộ điều phối ACP bên ngoài nhận một lời nhắc thuần với kết quả con và chỉ dẫn. Phong bì thô
<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>không bao giờ được gửi đến bộ điều phối bên ngoài hoặc được lưu bền vững dưới dạng văn bản bản ghi người dùng ACP. - Các mục bản ghi ACP 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. 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 trò chuyện do người dùng viết.
Phiên ACP một lần do phiên cha sở hữu
Phiên ACP một lần do phiên cha sở hữu
Các phiên ACP một lần do một lần chạy tác nhân khác sinh ra chạy như con nền,
tương tự tác nhân phụ:
- Phiên cha yêu cầu công việc bằng
sessions_spawn({ runtime: "acp", mode: "run" }). - Phiên con chạy trong phiên bộ điều phối ACP riêng của nó.
- Lượt con chạy trên cùng làn nền được dùng bởi các lần sinh tác nhân phụ gốc, vì vậy một bộ điều phối ACP chậm không chặn công việc phiên chính không liên quan.
- Báo cáo hoàn tất quay 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 một lời nhắc ACP thuần trước khi gửi đến bộ điều phối bên ngoài, vì vậy bộ điều phối không thấy các dấu ngữ cảnh môi trường chạy chỉ dành cho OpenClaw.
- Phiên cha viết lại kết quả con bằng giọng trợ lý thông thường khi cần phản hồi hướng đến người dùng.
sessions_send và phân phối A2A
sessions_send và phân phối A2A
sessions_send có thể nhắm đến phiên khác sau khi sinh. Với các phiên ngang hàng
thông thường, OpenClaw dùng đường dẫn tiếp theo tác nhân-đến-tác nhân (A2A)
sau khi chèn tin nhắn:- Chờ phản hồi của phiên đích.
- Tùy chọn cho phép bên yêu cầu và bên đích trao đổi số lượt tiếp theo có giới hạn.
- Yêu cầu đích tạo một tin nhắn thông báo.
- Gửi thông báo đó đến kênh hoặc luồng hiển thị.
tools.sessions.visibility rộng.OpenClaw chỉ bỏ qua lượt tiếp theo A2A khi bên yêu cầu là
phiên cha của chính phiên con ACP một lần do phiên cha sở hữu. Trong trường hợp đó,
chạy A2A bên trên hoàn tất tác vụ có thể đánh thức phiên cha bằng
kết quả của phiên con, chuyển tiếp phản hồi của phiên cha trở lại phiên con, và
tạo vòng lặp vọng phiên cha/phiên con. Kết quả sessions_send báo cáo
delivery.status="skipped" cho trường hợp phiên con được sở hữu đó vì
đường dẫn hoàn tất đã chịu trách nhiệm cho kết quả.Tiếp tục một phiên hiện có
Tiếp tục một phiên hiện có
Dùng Các trường hợp sử dụng phổ biến:
resumeSessionId để tiếp tục một phiên ACP trước đó thay vì
bắt đầu mới. Tác nhân phát lại lịch sử cuộc trò chuyện của nó qua
session/load, vì vậy nó tiếp tục với đầy đủ ngữ cảnh của những gì đã diễn ra trước đó.- Bàn giao một phiên Codex từ máy tính xách tay của bạn sang điện thoại — bảo tác nhân của bạn 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 không giao diện thông qua tác nhân của bạn.
- Tiếp tục công việc đã bị gián đoạn bởi lần khởi động lại gateway hoặc hết thời gian chờ do nhàn rỗi.
resumeSessionIdchỉ áp dụng khiruntime: "acp"; môi trường chạy tác nhân phụ mặc định bỏ qua trường chỉ dành cho ACP này.streamTochỉ áp dụng khiruntime: "acp"; môi trường chạy tác nhân phụ mặc định bỏ qua trường chỉ dành cho ACP này.resumeSessionIdlà ID tiếp tục ACP/bộ điều phối 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 sinh ACP và chính sách tác nhân đích trước khi điều phối, trong khi phần phụ trợ hoặc bộ điều phối ACP sở hữu quyền ủy quyền để tải ID thượng nguồn đó.resumeSessionIdkhôi phục lịch sử cuộc trò chuyện ACP thượng nguồn;threadvàmodevẫn áp dụng bình thường cho phiên OpenClaw mới bạn đang tạo, vì vậymode: "session"vẫn yêu cầuthread: true.- Tác nhân đích phải hỗ trợ
session/load(Codex và Claude Code có hỗ trợ). - Nếu không tìm thấy ID phiên, thao tác sinh sẽ lỗi với thông báo rõ ràng — không âm thầm quay về phiên mới.
Kiểm thử khói sau triển khai
Kiểm thử khói sau triển khai
Sau khi triển khai gateway, hãy chạy kiểm tra đầu cuối trực tiếp thay vì
tin vào kiểm thử đơn vị:
- Xác minh phiên bản gateway và commit đã triển khai trên máy chủ đích.
- Mở một phiên cầu nối ACPX tạm thời đến một tác nhân trực tiếp.
- Yêu cầu tác nhân đó gọi
sessions_spawnvớiruntime: "acp",agentId: "codex",mode: "run", và tác vụReply with exactly LIVE-ACP-SPAWN-OK. - Xác minh
accepted=yes, mộtchildSessionKeythật, và không có lỗi trình xác thực. - Dọn dẹp phiên cầu nối tạm thời.
mode: "run" và bỏ qua streamTo: "parent" —
mode: "session" có liên kết 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ú riêng biệt.Tương thích sandbox
Các phiên ACP hiện chạy trên môi trường chạy máy chủ, không bên trong sandbox OpenClaw. Hạn chế hiện tại:- Nếu phiên của bên yêu cầu đang bị sandbox, việc spawn ACP bị chặn cho cả
sessions_spawn({ runtime: "acp" })và/acp spawn. sessions_spawnvớiruntime: "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:
- Đối số đích tường minh (hoặc
--sessioncho/acp steer)- thử khóa
- rồi id phiên có dạng UUID
- rồi nhãn
- Ràng buộc luồng hiện tại (nếu cuộc trò chuyện/luồng này được ràng buộc với một phiên ACP).
- Dự phòng về phiên của bên yêu cầu hiện tại.
Unable to resolve session target: ...).
Điều khiển ACP
| Lệnh | Chức năng | Ví dụ |
|---|---|---|
/acp spawn | Tạo phiên ACP; tùy chọn ràng buộc hiện tại hoặc luồng. | /acp spawn codex --bind here --cwd /repo |
/acp cancel | Hủy lượt đang chạy cho phiên đích. | /acp cancel agent:codex:acp:<uuid> |
/acp steer | Gửi chỉ dẫn điều hướng tới phiên đang chạy. | /acp steer --session support inbox prioritize failing tests |
/acp close | Đóng phiên và gỡ ràng buộc các đích luồng. | /acp close |
/acp status | Hiển thị backend, chế độ, trạng thái, tùy chọn runtime, capability. | /acp status |
/acp set-mode | Đặt chế độ runtime cho phiên đích. | /acp set-mode plan |
/acp set | Ghi tùy chọn cấu hình runtime chung. | /acp set model openai/gpt-5.4 |
/acp cwd | Đặt ghi đè thư mục làm việc runtime. | /acp cwd /Users/user/Projects/repo |
/acp permissions | Đặt hồ sơ chính sách phê duyệt. | /acp permissions strict |
/acp timeout | Đặt thời gian chờ runtime (giây). | /acp timeout 120 |
/acp model | Đặt ghi đè mô hình runtime. | /acp model anthropic/claude-opus-4-6 |
/acp reset-options | Xóa các ghi đè tùy chọn runtime của phiên. | /acp reset-options |
/acp sessions | Liệt kê các phiên ACP gần đây từ kho lưu trữ. | /acp sessions |
/acp doctor | Sức khỏe backend, capability, bản sửa có thể hành động. | /acp doctor |
/acp install | In các bước cài đặt và bật có tính xác định. | /acp install |
/acp status hiển thị các tùy chọn runtime hiệu lực cùng với 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 capability. /acp sessions đọc
kho lưu trữ cho phiên đang được ràng buộc hiện tại hoặc phiên của bên yêu cầu; token đích
(session-key, session-id, hoặc session-label) được phân giải thông qua
khám phá phiên Gateway, bao gồm các gốc session.store
tùy chỉnh theo từng tác nhân.
Ánh xạ tùy chọn runtime
/acp có các lệnh tiện ích và một bộ đặt chung. Các
thao tác tương đương:
| Lệnh | Ánh xạ tới | Ghi chú |
|---|---|---|
/acp model <id> | khóa cấu hình runtime model | Với Codex ACP, OpenClaw chuẩn hóa openai-codex/<model> thành id mô hình adapter và ánh xạ các hậu tố suy luận dạng dấu gạch chéo như openai-codex/gpt-5.4/high thành reasoning_effort. |
/acp set thinking <level> | khóa cấu hình runtime thinking | Với Codex ACP, OpenClaw gửi reasoning_effort tương ứng khi adapter hỗ trợ. |
/acp permissions <profile> | khóa cấu hình runtime approval_policy | — |
/acp timeout <seconds> | khóa cấu hình runtime timeout | — |
/acp cwd <path> | ghi đè cwd runtime | Cập nhật trực tiếp. |
/acp set <key> <value> | chung | key=cwd dùng đường dẫn ghi đè cwd. |
/acp reset-options | xóa tất cả ghi đè runtime | — |
Harness acpx, thiết lập plugin và quyền
Để biết cấu hình harness acpx (bí danh Claude Code / Codex / Gemini CLI), các cầu nối MCP plugin-tools và OpenClaw-tools, và các chế độ quyền ACP, xem Tác nhân ACP — thiết lập.Khắc phục sự cố
| Triệu chứng | Nguyên nhân có thể | Cách khắc phục |
|---|---|---|
ACP runtime backend is not configured | Thiếu Plugin backend, bị tắt, hoặc bị chặn bởi plugins.allow. | Cài đặt và bật Plugin backend, đưa acpx vào plugins.allow khi allowlist đó được thiết lập, rồi chạy /acp doctor. |
ACP is disabled by policy (acp.enabled=false) | ACP bị tắt toàn cục. | Đặt acp.enabled=true. |
ACP dispatch is disabled by policy (acp.dispatch.enabled=false) | Điều phối tự động từ tin nhắn luồng thông thường bị tắt. | Đặt acp.dispatch.enabled=true để tiếp tục định tuyến luồng tự động; các lệnh gọi sessions_spawn({ runtime: "acp" }) rõ ràng vẫn hoạt động. |
ACP agent "<id>" is not allowed by policy | Tác tử không nằm trong allowlist. | Dùng agentId được phép hoặc cập nhật acp.allowedAgents. |
/acp doctor báo backend chưa sẵn sàng ngay sau khi khởi động | Kiểm tra phụ thuộc của Plugin hoặc tự sửa chữa vẫn đang chạy. | Chờ một lúc rồi chạy lại /acp doctor; nếu vẫn không khỏe, kiểm tra lỗi cài đặt backend và chính sách cho phép/từ chối Plugin. |
| Không tìm thấy lệnh harness | CLI adapter chưa được cài đặt, thiếu phụ thuộc Plugin đã chuẩn bị, hoặc lần tải npx đầu tiên thất bại với adapter không phải Codex. | Chạy /acp doctor, sửa phụ thuộc Plugin, cài đặt/làm nóng adapter trên máy chủ Gateway, hoặc cấu hình rõ ràng lệnh tác tử acpx. |
| Harness trả về lỗi không tìm thấy mô hình | ID mô hình hợp lệ với nhà cung cấp/harness khác nhưng không hợp lệ với mục tiêu ACP này. | Dùng một mô hình do harness đó liệt kê, cấu hình mô hình trong harness, hoặc bỏ ghi đè. |
| Lỗi xác thực nhà cung cấp từ harness | OpenClaw đang khỏe, nhưng CLI/nhà cung cấp mục tiêu chưa đăng nhập. | Đăng nhập hoặc cung cấp khóa nhà cung cấp bắt buộc trong môi trường máy chủ Gateway. |
Unable to resolve session target: ... | Token khóa/id/nhãn không hợp lệ. | Chạy /acp sessions, sao chép chính xác khóa/nhãn, rồi thử lại. |
--bind here requires running /acp spawn inside an active ... conversation | Dùng --bind here khi không có cuộc hội thoại đang hoạt động có thể bind. | Chuyển tới cuộc trò chuyện/kênh mục tiêu rồi thử lại, hoặc spawn không bind. |
Conversation bindings are unavailable for <channel>. | Adapter thiếu khả năng binding ACP cho cuộc hội thoại hiện tại. | Dùng /acp spawn ... --thread ... ở nơi được hỗ trợ, cấu hình bindings[] cấp cao nhất, hoặc chuyển tới kênh được hỗ trợ. |
--thread here requires running /acp spawn inside an active ... thread | Dùng --thread here bên ngoài ngữ cảnh luồng. | Chuyển tới luồng mục tiêu hoặc dùng --thread auto/off. |
Only <user-id> can rebind this channel/conversation/thread. | Người dùng khác sở hữu mục tiêu binding đang hoạt động. | Rebind với tư cách chủ sở hữu hoặc dùng cuộc hội thoại hay luồng khác. |
Thread bindings are unavailable for <channel>. | Adapter thiếu khả năng binding luồng. | Dùng --thread off hoặc chuyển tới adapter/kênh được hỗ trợ. |
Sandboxed sessions cannot spawn ACP sessions ... | ACP runtime nằm phía máy chủ; phiên yêu cầu đang ở trong sandbox. | Dùng runtime="subagent" từ các phiên sandbox, hoặc chạy ACP spawn từ một phiên không sandbox. |
sessions_spawn sandbox="require" is unsupported for runtime="acp" ... | Đã yêu cầu sandbox="require" cho ACP runtime. | Dùng runtime="subagent" cho yêu cầu sandbox bắt buộc, hoặc dùng ACP với sandbox="inherit" từ một phiên không sandbox. |
Cannot apply --model ... did not advertise model support | Harness mục tiêu không cung cấp chuyển đổi mô hình ACP chung. | Dùng harness quảng bá ACP models/session/set_model, dùng tham chiếu mô hình ACP của Codex, hoặc cấu hình mô hình trực tiếp trong harness nếu nó có cờ khởi động riêng. |
| Thiếu siêu dữ liệu ACP cho phiên đã bind | Siêu dữ liệu phiên ACP đã cũ/bị xóa. | Tạo lại bằng /acp spawn, rồi rebind/focus luồng. |
AcpRuntimeError: Permission prompt unavailable in non-interactive mode | permissionMode chặn ghi/thực thi trong phiên ACP không tương tác. | Đặt plugins.entries.acpx.config.permissionMode thành approve-all và khởi động lại gateway. Xem Cấu hình quyền. |
| Phiên ACP thất bại sớm với rất ít đầu ra | Lời nhắc quyền bị chặn bởi permissionMode/nonInteractivePermissions. | Kiểm tra nhật ký gateway để tìm AcpRuntimeError. Để có đầy đủ quyền, đặt permissionMode=approve-all; để suy giảm nhẹ nhàng, đặt nonInteractivePermissions=deny. |
| Phiên ACP bị treo vô thời hạn sau khi hoàn tất công việc | Tiến trình harness đã kết thúc nhưng phiên ACP không báo hoàn tất. | Theo dõi bằng ps aux | grep acpx; tự kết thúc các tiến trình cũ. |
Harness thấy <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> | Phong bì sự kiện nội bộ bị rò rỉ qua ranh giới ACP. | Cập nhật OpenClaw và chạy lại luồng hoàn tất; các harness bên ngoài chỉ nên nhận lời nhắc hoàn tất dạng văn bản thuần. |