Chuyển đến nội dung chính

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Để xem phần tổng quan, sổ tay vận hành và các khái niệm, hãy xem tác tử ACP. Các phần dưới đây trình bày cấu hình harness acpx, thiết lập plugin cho các cầu nối MCP và cấu hình quyền. Chỉ dùng trang này khi bạn đang thiết lập tuyến ACP/acpx. Với cấu hình runtime app-server Codex gốc, hãy dùng harness Codex. Với khóa API OpenAI hoặc cấu hình nhà cung cấp mô hình OAuth của Codex, hãy dùng OpenAI. Codex có hai tuyến OpenClaw:
TuyếnCấu hình/lệnhTrang thiết lập
app-server Codex gốc/codex ..., tham chiếu tác tử openai/gpt-*harness Codex
Bộ điều hợp ACP Codex rõ ràng/acp spawn codex, runtime: "acp", agentId: "codex"Trang này
Ưu tiên tuyến gốc trừ khi bạn cần rõ ràng hành vi ACP/acpx.

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

Các bí danh harness tích hợp sẵn của acpx hiện tại:
  • claude
  • codex
  • copilot
  • cursor (Cursor CLI: cursor-agent acp)
  • droid
  • gemini
  • iflow
  • kilocode
  • kimi
  • kiro
  • openclaw
  • opencode
  • pi
  • qwen
Khi OpenClaw dùng backend acpx, hãy ưu tiên các giá trị này cho agentId trừ khi cấu hình acpx của bạn định nghĩa bí danh tác tử tùy chỉnh. Nếu bản cài đặt Cursor cục bộ của bạn vẫn cung cấp ACP dưới dạng agent acp, hãy ghi đè lệnh tác tử cursor trong cấu hình acpx thay vì thay đổi mặc định tích hợp sẵn. Việc dùng acpx CLI trực tiếp cũng có thể nhắm tới các bộ điều hợp tùy ý qua --agent <command>, nhưng lối thoát thô đó là một tính năng của acpx CLI (không phải đường dẫn agentId OpenClaw thông thường). Việc điều khiển mô hình phụ thuộc vào năng lực của bộ điều hợp. Tham chiếu mô hình ACP của Codex được OpenClaw chuẩn hóa trước khi khởi động. Các harness khác cần ACP models cùng hỗ trợ session/set_model; nếu harness không cung cấp năng lực ACP đó lẫn cờ mô hình khởi động riêng, OpenClaw/acpx không thể bắt buộc chọn mô hình.

​
Cấu hình bắt buộc

Nền tảng ACP cốt lõi: 
{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}
Cấu hình liên kết luồng tùy thuộc vào bộ điều hợp kênh. Ví dụ cho Discord: 
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnSessions: true,
      },
    },
  },
}
Nếu spawn ACP gắn với luồng không hoạt động, trước tiên hãy kiểm tra cờ tính năng của bộ điều hợp:
  • Discord: channels.discord.threadBindings.spawnSessions=true
Liên kết cuộc trò chuyện hiện tại không yêu cầu tạo luồng con. Chúng yêu cầu ngữ cảnh cuộc trò chuyện đang hoạt động và bộ điều hợp kênh cung cấp liên kết cuộc trò chuyện ACP. Xem Tham chiếu cấu hình.

​
Thiết lập plugin cho backend acpx

Các bản cài đặt đóng gói dùng plugin runtime @openclaw/acpx chính thức cho ACP. Cài đặt và bật plugin này trước khi dùng các phiên harness ACP: 
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
Các checkout mã nguồn cũng có thể dùng plugin workspace cục bộ sau pnpm install. Bắt đầu với: 
/acp doctor
Nếu bạn đã tắt acpx, từ chối nó qua plugins.allow / plugins.deny, hoặc muốn chuyển lại về plugin đóng gói, hãy dùng đường dẫn gói rõ ràng: 
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
Cài đặt workspace cục bộ trong quá trình phát triển: 
openclaw plugins install ./path/to/local/acpx-plugin
Sau đó xác minh tình trạng backend: 
/acp doctor

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

Theo mặc định, plugin acpx thăm dò backend ACP nhúng trong khi Gateway khởi động và chờ thăm dò đó trước tín hiệu ready của gateway. Đặt OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 để bỏ qua thăm dò khởi động và đăng ký backend theo kiểu lazy. Chạy /acp doctor để thăm dò theo yêu cầu rõ ràng. Ghi đè lệnh hoặc phiên bản trong cấu hình plugin: 
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}
  • command chấp nhận đường dẫn tuyệt đối, đường dẫn tương đối (được phân giải từ workspace OpenClaw), hoặc tên lệnh.
  • expectedVersion: "any" tắt khớp phiên bản nghiêm ngặt.
  • Đường dẫn command tùy chỉnh tắt tự động cài đặt cục bộ của plugin.
Ghi đè một lệnh tác tử ACP riêng lẻ bằng đối số có cấu trúc khi một đường dẫn hoặc giá trị cờ cần giữ nguyên là một token argv: 
{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "agents": {
            "claude": {
              "command": "node",
              "args": ["/path/to/custom adapter.mjs", "--verbose"]
            }
          }
        }
      }
    }
  }
}
  • agents.<id>.command là tệp thực thi hoặc chuỗi lệnh hiện có cho tác tử ACP đó.
  • agents.<id>.args là tùy chọn. Mỗi mục mảng được shell-quote trước khi OpenClaw truyền nó qua registry chuỗi lệnh acpx hiện tại.
Xem Plugin.

​
Tự động cài đặt phụ thuộc

Khi bạn cài đặt OpenClaw toàn cục bằng npm install -g openclaw, các phụ thuộc runtime acpx (nhị phân theo nền tảng) được cài đặt tự động qua hook postinstall. Nếu cài đặt tự động thất bại, gateway vẫn khởi động bình thường và báo phụ thuộc bị thiếu qua openclaw acp doctor.

​
Cầu nối MCP công cụ plugin

Theo mặc định, các phiên ACPX không cung cấp công cụ do plugin OpenClaw đăng ký cho harness ACP. Nếu bạn muốn các tác tử ACP như Codex hoặc Claude Code gọi các công cụ plugin OpenClaw đã cài đặt như recall/store bộ nhớ, hãy bật cầu nối chuyên dụng: 
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
Việc này làm gì:
  • Chèn một máy chủ MCP tích hợp sẵn tên là openclaw-plugin-tools vào bootstrap phiên ACPX.
  • Cung cấp các công cụ plugin đã được đăng ký bởi các plugin OpenClaw đã cài đặt và đang bật.
  • Giữ tính năng này là rõ ràng và mặc định tắt.
Ghi chú về bảo mật và tin cậy:
  • Điều này mở rộng bề mặt công cụ của harness ACP.
  • Tác tử ACP chỉ có quyền truy cập các công cụ plugin đã hoạt động trong gateway.
  • Hãy xem đây là cùng ranh giới tin cậy như việc cho phép các plugin đó thực thi trong chính OpenClaw.
  • Xem xét các plugin đã cài đặt trước khi bật tính năng này.
mcpServers tùy chỉnh vẫn hoạt động như trước. Cầu nối plugin-tools tích hợp sẵn là một tiện ích chọn bật bổ sung, không phải thay thế cho cấu hình máy chủ MCP chung.

​
Cầu nối MCP công cụ OpenClaw

Theo mặc định, các phiên ACPX cũng không cung cấp công cụ OpenClaw tích hợp sẵn thông qua MCP. Bật cầu nối công cụ lõi riêng khi một tác tử ACP cần các công cụ tích hợp sẵn đã chọn như cron: 
openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
Việc này làm gì:
  • Chèn một máy chủ MCP tích hợp sẵn tên là openclaw-tools vào bootstrap phiên ACPX.
  • Cung cấp các công cụ OpenClaw tích hợp sẵn đã chọn. Máy chủ ban đầu cung cấp cron.
  • Giữ việc phơi bày công cụ lõi là rõ ràng và mặc định tắt.

​
Cấu hình thời gian chờ runtime

Plugin acpx mặc định đặt thời gian chờ các lượt runtime nhúng là 120 giây. Điều này cho các harness chậm hơn như Gemini CLI đủ thời gian để hoàn tất khởi động và khởi tạo ACP. Ghi đè giá trị này nếu máy chủ của bạn cần giới hạn runtime khác: 
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
Khởi động lại gateway sau khi thay đổi giá trị này.

​
Cấu hình tác tử thăm dò tình trạng

Khi /acp doctor hoặc thăm dò khởi động kiểm tra backend, plugin acpx đi kèm sẽ thăm dò một tác tử harness. Nếu acp.allowedAgents được đặt, nó mặc định là tác tử được phép đầu tiên; nếu không, mặc định là codex. Nếu triển khai của bạn cần một tác tử ACP khác cho kiểm tra tình trạng, hãy đặt tác tử thăm dò rõ ràng: 
openclaw config set plugins.entries.acpx.config.probeAgent claude
Khởi động lại gateway sau khi thay đổi giá trị này.

​
Cấu hình quyền

Các phiên ACP chạy không tương tác — không có TTY để phê duyệt hoặc từ chối lời nhắc quyền ghi tệp và thực thi shell. Plugin acpx cung cấp hai khóa cấu hình kiểm soát cách xử lý quyền: Các quyền harness ACPX này tách biệt với phê duyệt exec của OpenClaw và tách biệt với các cờ bỏ qua của nhà cung cấp backend CLI như Claude CLI --permission-mode bypassPermissions. ACPX approve-all là công tắc khẩn cấp cấp harness cho các phiên ACP.

​
permissionMode

Kiểm soát những thao tác tác tử harness có thể thực hiện mà không cần nhắc.
Giá trịHành vi
approve-allTự động phê duyệt mọi lệnh ghi tệp và lệnh shell.
approve-readsChỉ tự động phê duyệt thao tác đọc; ghi và exec cần lời nhắc.
deny-allTừ chối mọi lời nhắc quyền.

​
nonInteractivePermissions

Kiểm soát điều xảy ra khi lẽ ra lời nhắc quyền sẽ hiển thị nhưng không có TTY tương tác khả dụng (điều này luôn đúng với các phiên ACP).
Giá trịHành vi
failHủy phiên với AcpRuntimeError. (mặc định)
denyÂm thầm từ chối quyền và tiếp tục (suy giảm nhẹ nhàng).

​
Cấu hình

Đặt qua cấu hình plugin: 
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
Khởi động lại gateway sau khi thay đổi các giá trị này.
OpenClaw mặc định dùng permissionMode=approve-reads và nonInteractivePermissions=fail. Trong các phiên ACP không tương tác, bất kỳ thao tác ghi hoặc exec nào kích hoạt lời nhắc quyền đều 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, hãy đặt nonInteractivePermissions thành deny để các phiên suy giảm nhẹ nhàng thay vì bị crash.

​
Liên quan