​

Tác nhân ACP

​

Quy trình vận hành nhanh

1. Khởi tạo một phiên:
   • /acp spawn codex --mode persistent --thread auto
2. Làm việc trong thread đã gắn (hoặc nhắm mục tiêu vào khóa phiên đó một cách rõ ràng).
3. Kiểm tra trạng thái runtime:
   • /acp status
4. Điều chỉnh các tùy chọn runtime khi cần:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Điều chỉnh một phiên đang hoạt động mà không thay thế ngữ cảnh:
   • /acp steer tighten logging and continue
6. Dừng công việc:
   • /acp cancel (dừng lượt hiện tại), hoặc
   • /acp close (đóng phiên + xóa các liên kết)

​

Bắt đầu nhanh cho người dùng

• “Bắt đầu một phiên Codex liên tục trong một thread ở đây và giữ nó tập trung.”
• “Chạy cái này như một phiên Claude Code ACP một lần và tóm tắt kết quả.”
• “Sử dụng Gemini CLI cho nhiệm vụ này trong một thread, sau đó giữ các theo dõi trong cùng thread đó.”

1. Chọn runtime: "acp".
2. Xác định mục tiêu harness được yêu cầu (agentId, ví dụ codex).
3. Nếu yêu cầu gắn thread và kênh hiện tại hỗ trợ, gắn phiên ACP vào thread.
4. Định tuyến các tin nhắn theo dõi thread đến cùng phiên ACP đó cho đến khi không còn tập trung/đóng/hết hạn.

​

ACP so với sub-agents

​

Phiên gắn liền với thread (không phụ thuộc kênh)

• OpenClaw gắn một thread vào một phiên ACP mục tiêu.
• Các tin nhắn theo dõi trong thread đó được định tuyến đến phiên ACP đã gắn.
• Đầu ra ACP được gửi lại cho cùng thread đó.
• Không tập trung/đóng/lưu trữ/hết thời gian chờ hoặc hết tuổi tối đa sẽ xóa liên kết.

• acp.enabled=true
• acp.dispatch.enabled được bật theo mặc định (đặt false để tạm dừng dispatch ACP)
• Cờ spawn thread-adapter ACP được bật (đặc thù của adapter)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Các kênh hỗ trợ thread

• Bất kỳ adapter kênh nào cung cấp khả năng gắn kết phiên/thread.
• Hỗ trợ tích hợp sẵn hiện tại:
  • Các thread/kênh Discord
  • Các 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 gắn kết.

​

Cài đặt cụ thể cho kênh

​

Mô hình liên kết

• bindings[].type="acp" đánh dấu một liên kết cuộc trò chuyện ACP liên tục.
• bindings[].match xác định cuộc trò chuyện mục tiêu:
  • Kênh hoặc thread Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Chủ đề diễn đàn Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
• bindings[].agentId là id tác nhân OpenClaw sở hữu.
• Các ghi đè ACP tùy chọn nằm dưới bindings[].acp:
  • mode (persistent hoặc oneshot)
  • label
  • cwd
  • backend

​

Mặc định runtime cho mỗi tác nhân

• 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

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. Mặc định ACP toàn cầu (ví dụ acp.backend)

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

• OpenClaw đảm bảo phiên ACP được cấu hình tồn tại trước khi sử dụng.
• Các tin nhắn trong kênh hoặc chủ đề đó được định tuyến đến phiên ACP đã cấu hình.
• Trong các cuộc trò chuyện đã gắn, /new và /reset đặt lại cùng khóa phiên ACP tại chỗ.
• Các liên kết runtime tạm thời (ví dụ được tạo bởi các luồng tập trung thread) vẫn áp dụng khi có.

​

Bắt đầu các phiên ACP (giao diện)

​

Từ sessions_spawn

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

• runtime mặc định là subagent, vì vậy hãy đặt runtime: "acp" rõ ràng cho các phiên ACP.
• Nếu agentId bị bỏ qua, 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 gắn liền liên tục.

• task (bắt buộc): lời nhắc ban đầu được gửi đến phiên ACP.
• runtime (bắt buộc cho ACP): phải là "acp".
• agentId (tùy chọn): id harness mục tiêu ACP. Sẽ sử dụng acp.defaultAgent nếu được đặt.
• thread (tùy chọn, mặc định false): yêu cầu luồng gắn kết thread khi được hỗ trợ.
• mode (tùy chọn): run (một lần) hoặc session (liên tục).
  • mặc định là run
  • nếu thread: true và chế độ bị bỏ qua, OpenClaw có thể mặc định hành vi liên tục theo đường dẫn runtime
  • mode: "session" yêu cầu thread: true
• cwd (tùy chọn): thư mục làm việc runtime được yêu cầu (được xác thực bởi chính sách backend/runtime).
• label (tùy chọn): nhãn hướng đến người vận hành được sử dụng trong văn bản phiên/banner.
• resumeSessionId (tùy chọn): tiếp tục một phiên ACP hiện có thay vì tạo một 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".
• streamTo (tùy chọn): "parent" truyền các 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.
  • Khi có sẵn, các phản hồi được chấp nhận bao gồm streamLogPath trỏ đến một log JSONL theo phạm vi phiên (<sessionId>.acp-stream.jsonl) bạn có thể theo dõi để có lịch sử chuyển tiếp đầy đủ.

​

Tiếp tục một phiên hiện có

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

• Chuyển một phiên Codex từ laptop của bạn sang điện thoại — yêu cầu tác nhân của bạn tiếp tục từ nơi bạn đã dừng lại
• Tiếp tục một phiên mã hóa bạn đã bắt đầu tương tác trong CLI, bây giờ không có đầu qua tác nhân của bạn
• Tiếp tục công việc bị gián đoạn bởi khởi động lại gateway hoặc hết thời gian chờ

• resumeSessionId yêu cầu runtime: "acp" — trả về lỗi nếu được sử dụng với runtime sub-agent.
• resumeSessionId khôi phục lịch sử cuộc trò chuyện ACP thượng nguồn; thread và mode vẫn áp dụng bình thường cho phiên OpenClaw mới bạn đang tạo, vì vậy mode: "session" vẫn yêu cầu thread: true.
• Tác nhân mục tiêu phải hỗ trợ session/load (Codex và Claude Code có).
• Nếu không tìm thấy ID phiên, spawn sẽ thất bại với một lỗi rõ ràng — không có fallback im lặng sang một phiên mới.

​

Kiểm tra nhanh của người vận hành

1. Xác minh phiên bản/commit gateway đã triển khai trên máy chủ mục tiêu.
2. Xác nhận mã nguồn đã triển khai bao gồm chấp nhận dòng dõi ACP trong src/gateway/sessions-patch.ts (subagent:* hoặc acp:* sessions).
3. 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 (ví dụ razor(main) trên jpclawhq).
4. Yêu cầu tác nhân đó gọi sessions_spawn với:
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: Reply with exactly LIVE-ACP-SPAWN-OK
5. Xác minh tác nhân báo cáo:
   • accepted=yes
   • một childSessionKey thực
   • không có lỗi validator
6. Dọn dẹp phiên cầu nối ACPX tạm thời.

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

• Giữ bài kiểm tra nhanh này trên mode: "run" trừ khi bạn đang cố ý kiểm tra các phiên ACP liên tục gắn liền với thread.
• Không yêu cầu streamTo: "parent" cho cổng cơ bản. Đường dẫn đó phụ thuộc vào khả năng của người yêu cầu/phiên và là một kiểm tra tích hợp riêng biệt.
• Xem xét thử nghiệm mode: "session" gắn liền với thread như một lần vượt qua tích hợp phong phú thứ hai từ một thread Discord thực hoặc chủ đề Telegram.

​

Tương thích với Sandbox

• Nếu phiên yêu cầu được sandbox, spawn ACP bị chặn cho cả sessions_spawn({ runtime: "acp" }) và /acp spawn.
  • Lỗi: Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn với runtime: "acp" không hỗ trợ sandbox: "require".
  • Lỗi: sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

​

Từ lệnh /acp

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --thread here

• --mode persistent|oneshot
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

​

Giải quyết mục tiêu phiên

1. Đối số mục tiêu rõ ràng (hoặc --session cho /acp steer)
   • thử khóa
   • sau đó ID phiên có dạng UUID
   • sau đó nhãn
2. Liên kết thread hiện tại (nếu cuộc trò chuyện/thread này được gắn vào một phiên ACP)
3. Fallback phiên yêu cầu hiện tại

​

Chế độ spawn thread

• Trên các bề mặt không gắn kết thread, hành vi mặc định là off.
• Spawn gắn kết thread yêu cầu hỗ trợ chính sách kênh:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Điều khiển ACP

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

​

Sổ tay lệnh ACP

​

Ánh xạ tùy chọn runtime

• /acp model <id> ánh xạ đến khóa cấu hình runtime model.
• /acp permissions <profile> ánh xạ đến khóa cấu hình runtime approval_policy.
• /acp timeout <seconds> ánh xạ đến khóa cấu hình runtime timeout.
• /acp cwd <path> cập nhật ghi đè cwd runtime trực tiếp.
• /acp set <key> <value> là đường dẫn chung.
  • Trường hợp đặc biệt: key=cwd sử dụng đường dẫn ghi đè cwd.
• /acp reset-options xóa tất cả các ghi đè runtime cho phiên mục tiêu.

​

Hỗ trợ harness acpx (hiện tại)

• pi
• claude
• codex
• opencode
• gemini
• kimi

​

Cấu hình cần thiết

{
  acp: {
    enabled: true,
    // Tùy chọn. Mặc định là true; đặt false để tạm dừng dispatch ACP trong khi giữ các điều khiển /acp.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

• Discord: channels.discord.threadBindings.spawnAcpSessions=true

​

Thiết lập plugin cho backend acpx

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

openclaw plugins install ./extensions/acpx

/acp doctor

​

Cấu hình lệnh và phiên bản acpx

1. Lệnh mặc định là extensions/acpx/node_modules/.bin/acpx.
2. Phiên bản dự kiến mặc định là ghim của extension.
3. Khởi động đăng ký backend ACP ngay lập tức là không sẵn sàng.
4. Một công việc đảm bảo nền xác minh acpx --version.
5. Nếu binary cục bộ plugin bị thiếu hoặc không khớp, nó chạy: npm install --omit=dev --no-save acpx@<pinned> và xác minh lại.

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

• command chấp nhận một đường dẫn tuyệt đối, đường dẫn tương đối, hoặc tên lệnh (acpx).
• Đường dẫn tương đối được giải quyết từ thư mục workspace OpenClaw.
• expectedVersion: "any" vô hiệu hóa khớp phiên bản nghiêm ngặt.
• Khi command trỏ đến một binary/đường dẫn tùy chỉnh, cài đặt tự động cục bộ plugin bị vô hiệu hóa.
• Khởi động OpenClaw vẫn không bị chặn trong khi kiểm tra sức khỏe backend chạy.

​

Cấu hình quyền

​

permissionMode

​

nonInteractivePermissions

​

Cấu hình

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Quan trọng: OpenClaw hiện mặc định permissionMode=approve-reads và nonInteractivePermissions=fail. Trong các phiên ACP không tương tác, bất kỳ ghi hoặc thực thi nào kích hoạt một lời nhắc quyền có thể thất bại với AcpRuntimeError: Permission prompt unavailable in non-interactive mode. Nếu bạn cần hạn chế quyền, đặt nonInteractivePermissions thành deny để các phiên suy giảm nhẹ nhàng thay vì bị lỗi.

​

Khắc phục sự cố