Bundle Pluginsource linkedVerified

ACPX Runtimev2026.10.6

OpenClaw ACP runtime backend with plugin-owned session and transport management.

@openclaw/acpx·runtime acpx·by @openclaw

openclaw bundles install clawhub:@openclaw/acpx

Latest release: v2026.10.6Download zip

Compatibility

Built With Open Claw Version

2026.10.6

Min Gateway Version

>=2026.4.25

Plugin Api Range

>=2026.10.6

Security Scan

VirusTotal

Benign

View report →

OpenClaw

Suspicious

high confidence

ℹ

Credentials

The README explicitly discloses host execution without OpenClaw sandbox confinement. Classic runtime defaults are approve-reads and fail when interactive permissions are unavailable; optional tool bridges default off.

ℹ

Install Mechanism

The manifest pins acpx and bundled adapters, and repair targets the plugin-local installation. Documented Kilocode and OpenCode launchers use unversioned npx packages, introducing release drift.

Instruction Scope

SKILL.md directs recovery to remove broken agent overrides from ~/.acpx/config.json before retrying. It does not require approval, a backup, or verification that removing the configured command preserves user-selected controls.

Persistence & Privilege

Persistent sessions and plugin state are expected. Removing user-wide adapter overrides during a single failed session can also change future launches, without a required rollback path.

✓

Purpose & Capability

Routing requested work to external coding agents, maintaining sessions, and providing optional tool bridges fit the declared ACP runtime purpose.

Scan Findings in Context

[EA2] expected: The cited passage avoids requiring users to run CLI commands manually; it does not authorize arbitrary destructive actions. Requested session creation is purpose-aligned, and native permission requests have approval handling.

[RP1] expected: The documented Kilocode launcher uses npx -y @kilocode/cli without a version. This is a disclosed ACP adapter, with mutable dependency exposure rather than demonstrated malicious replacement.

[RP1] expected: The documented OpenCode launcher uses npx -y opencode-ai without a version. Pinning acpx does not pin this separately fetched CLI; its use still matches the integration purpose.

[SQP-2] unexpected: Plugin-local pinned installation is proportionate repair. The material concern is extending recovery into persistent override removal without requiring disclosure, approval, or backup.

[SDI-1] unexpected: The skill explicitly instructs removal of broken user-wide agent overrides. A missing adapter command alone does not establish that discarding the user's launch configuration is appropriate.

What to consider before installing

Review the recovery instructions before installing. Back up ~/.acpx/config.json and require approval before removing custom commands or changing persistent settings. Pin external CLI versions where possible, and consider the disclosed host access granted to native coding agents.

✗

dist/.setup/service-42j3ASsm.mjs:608

Shell command execution detected (child_process).

Patterns worth reviewing

These patterns may indicate risky behavior. Check the VirusTotal and OpenClaw results above for context-aware analysis before installing.

Verification

Tier

source linked

Scope

artifact only

Summary

Validated package structure and linked the release to source metadata.

Source

github.com/openclaw/openclaw

Commit

fe06181dc5ec

Tag

fe06181dc5ecc01cf8904abbfc26925925efefbc

Provenance

Scan status

suspicious

@openclaw/acpx

Official ACP runtime backend for OpenClaw.

ACPx lets OpenClaw run external coding harnesses through the Agent Client Protocol while OpenClaw still owns sessions, channels, delivery, permissions, and Gateway state.

Install

openclaw plugins install @openclaw/acpx

Restart the Gateway after installing or updating the plugin.

The generated Codex and Claude ACP wrappers prefer the installed adapter while its entry file exists. If plugin capture cleanup removes that file, the next launch uses the existing pinned npm exec / npx fallback. This may require registry access when the pinned package is not cached. Restart the Gateway after updating to regenerate wrappers written by an older plugin version.

What it provides

ACP-backed agent runtime sessions.
Plugin-owned session and transport management.
MCP bridge helpers for OpenClaw tools and plugin tools.
Static runtime assets used by the ACP process bridge.

If the Gateway restarts before a one-shot session receives its first prompt, ACPX reuses the initialized conversation when the agent supports loading or resuming sessions. Completed one-shot runs still start a fresh conversation.

Native agents in the model picker

Install GitHub Copilot CLI, Kilo Code, OpenCode, Pi ACP, or Qwen Code and complete its login on the Gateway host, then refresh the model catalog. Choose one of its models to use that agent in ordinary chat. The agent owns its credentials; OpenClaw keeps the conversation transcript and asks for approval when the agent requests permission. Pi does not request tool approval unless an extension adds it. The same selection works in the web app and channels.

The runtime and provider IDs are acp-copilot, acp-kilocode, acp-opencode, acp-pi, and acp-qwen. Each model keeps its native ID, including any slashes. Configured ACP agent commands take precedence over installed defaults. Catalog refresh uses installed commands and does not install missing agents. Explicit ACP commands and bindings keep their existing agent names.

Models settings lists detected agents on the Gateway machine. Turn each native agent on or off there, or set plugins.entries.acpx.config.nativeAgents.<id> to false (copilot, kilocode, opencode, pi, or qwen). Missing flags are enabled. Disabling an agent prevents new native turns and catalog discovery without interrupting a running turn or deleting history. Classic ACP commands and acp.allowedAgents keep their existing behavior. Detection checks installed executables; it does not prove that an agent is logged in or can serve a model.

For GitHub Copilot CLI, run copilot login under the Gateway's OS account before refreshing the catalog. Copilot owns GitHub authentication, model access, and plan usage. Its explicitly configured BYOK providers remain CLI-owned and can incur separate API charges; OpenClaw does not select a BYOK route for it. See the Copilot setup and billing notes.

Native picker runtimes run on the Gateway host and use the native app's permissions. OpenClaw checks that execution choice before dispatching a chat turn; ACP runners do not implement OpenClaw sandboxing or workspace-only filesystem confinement.

When optional chat restrictions cannot be enforced, an administrator can choose Continue for this chat to use the native app's permissions. This grants Full Access and turns off optional sandboxing for that chat only; agent-wide and global settings stay unchanged. After a refused message, confirmation retries that message once. Confirming a model selection without a pending message does not send anything.

A creator-role-required sandbox cannot be removed, and remote execution placement is not supported. Choose a compatible runtime when those boundaries must remain. OpenClaw's Read Only, Guarded, and Workspace permission modes are not supported by these native runtimes.

Native tool permission requests still require their one-shot approval. Once approved, delegated filesystem writes do not encounter a second ACPX terminal approval gate. Classic ACP sessions keep their configured permissionMode. The ACP client's delegated filesystem remains rooted at its session cwd; this is not a sandbox for the native process's own filesystem access.

Catalog refresh closes its local connection. The native agent owns any history it creates. Reset and deletion close the local session and prevent its reuse, including after a Gateway restart. Native history stays with the agent; these operations do not delete it.

Configure

Use the ACP docs for harness-specific setup, permission modes, and model/runtime selection:

Package

Plugin id: acpx
Package: @openclaw/acpx
Minimum OpenClaw host: 2026.4.25