What are thread-bound agents in OpenClaw?

Thread-bound agents are ACP agent runtimes that are bound to a specific conversation thread rather than shared globally across all threads. Each thread gets its own runtime with full dispatch integration and lifecycle controls. This allows multi-agent workflows where different specialist agents handle different threads inside the same OpenClaw gateway.

What is the difference between ACP and MCP in OpenClaw?

ACP is about an external client driving the agent runtime itself — starting it, binding it to threads, and controlling its lifecycle. MCP (Model Context Protocol) is about tools and skills the agent can call once it is running, such as web search, file access, or database queries. ACP governs how the agent is operated; MCP governs what the agent can do.

Which version of OpenClaw introduced ACP thread-bound agents?

First-class ACP thread-bound agent runtimes shipped in OpenClaw v2026.2.26, released February 27, 2026. ACP dispatch is enabled by default from that release onward. Earlier releases included ACP client permission hardening as a security fix, but thread-bound runtimes and the agent routing CLI are v2026.2.26 features.

← Home

Feature Guide

OpenClaw ACP Agents — Agent Client Protocol & Thread-Bound Runtimes

Q: What is ACP in OpenClaw?

ACP (Agent Client Protocol) is a protocol that lets an external client or editor drive an OpenClaw agent runtime. The client connects to a running agent, controls session lifecycle, sends tasks, and reads structured results — useful for IDEs, orchestration systems, and parent agents that need to treat OpenClaw as a managed subprocess.

OpenClaw v2026.2.26 shipped first-class ACP (Agent Client Protocol) thread-bound agent runtimes alongside a full external secrets management workflow and a new agent routing CLI. This guide explains what ACP is, what "thread-bound" means in practice, and when you would reach for ACP instead of MCP.

What Is ACP (Agent Client Protocol)?

ACP — Agent Client Protocol — is a protocol that allows an external client or editor to drive an agent runtime. Instead of the agent operating autonomously from a fixed startup config, an ACP client can connect to a running agent, send instructions, receive structured responses, and control the lifecycle of agent sessions from the outside. The client is in the driving seat; the agent runtime executes on its behalf.

This is distinct from a simple API call. ACP is designed for ongoing, stateful interaction between a client and an agent — the kind of connection an IDE, a multi-agent orchestration system, or an automation platform needs when it wants to treat the agent as a persistent subprocess rather than a one-shot endpoint.

ACP dispatch is enabled by default in OpenClaw since v2026.2.26. If you need to disable it for a specific deployment you can do so explicitly in the agent configuration. Earlier releases carried ACP client permission hardening (requiring trusted tool IDs) as a security fix — the v2026.2.26 release promoted ACP from an internal capability to a first-class runtime feature.

Thread-Bound Agent Runtimes in OpenClaw v2026.2.26

The headline ACP change in v2026.2.26 is that ACP agents are now first-class runtimes for thread sessions. Concretely, this means:

Each conversation thread can have its own bound agent runtime rather than all threads sharing a single global agent instance.
The bound runtime has full dispatch integration — the thread and the agent have a stable, named relationship so messages route to the right runtime without ambiguity.
The runtime lifecycle is tied to the thread: it can be started, paused, or torn down per-thread rather than only at the gateway level.

In practical terms, "thread-bound" means that a multi-agent workflow can assign specialist agents to specific conversations or tasks. One thread might be bound to a research agent, another to a coding agent, another to a summarization agent — all running inside the same OpenClaw gateway but isolated at the thread level. The orchestrating client uses ACP to bind, unbind, and query agent state per thread.

External Secrets Management

Thread-bound ACP runtimes ship alongside a complete external secrets management workflow in the same v2026.2.26 release. The connection is intentional: if an agent runtime is going to be driven by an external client, that client should not have to inline API keys and credentials directly into the runtime config.

The secrets workflow adds four new CLI commands covering audit, configure, apply, and reload. The workflow supports runtime snapshot activation — you can rotate credentials or apply a new secrets snapshot without restarting the gateway. For production deployments where uptime matters, this removes one of the most disruptive maintenance tasks.

Agents can reference managed secrets by name rather than embedding raw keys. A later release (v2026.3.x) expanded SecretRef coverage to 64 targets, integrating throughout runtime collectors and planning, apply, and audit flows. Unresolved references trigger fail-fast handling rather than silently falling back to an empty string.

For the exact command names and config field names, consult the official v2026.2.26 release notes — this guide describes capabilities at a high level and avoids inventing flag syntax that may have changed across patch releases.

Agent Routing CLI

Alongside ACP thread-bound runtimes, v2026.2.26 shipped new CLI commands for account-scoped agent route management under the openclaw agents namespace. The commands cover listing bindings, creating a binding between an agent and a target context, and removing a binding.

Before this addition, routing an agent to a specific channel or thread required editing configuration files directly and restarting the gateway. The routing CLI makes these changes operational commands that can be scripted, audited, and reversed without a config file edit or service restart.

Combined with ACP dispatch, the routing CLI gives operators a full programmatic surface for agent placement: decide which agent handles which thread, apply the binding via CLI, and have the ACP dispatch layer route traffic accordingly.

ACP vs MCP — Which One Do You Need?

ACP and MCP (Model Context Protocol) are often mentioned together in the OpenClaw ecosystem, but they solve different problems:

ACP — A Client Driving an Agent Runtime

ACP is about the relationship between an external client and the agent runtime itself. The client connects to a running agent, controls session lifecycle, sends tasks, and reads structured results. Use ACP when you want an IDE, an orchestration system, or a parent agent to treat OpenClaw as a managed subprocess — something it can start, instruct, and stop programmatically.

The thread-bound runtime model is the clearest expression of this: a client binds a runtime to a thread, the runtime handles that thread's messages, and the client can replace or restart the runtime without disrupting other threads.

MCP — Tools and Skills the Agent Can Call

MCP is about what the agent can do once it is running. MCP servers expose tools — web search, file access, database queries, calendar operations — that the agent can call during a conversation. The agent is the client in an MCP relationship; it reaches out to MCP servers to extend its capabilities.

Use MCP when you want to give your agent access to a new tool or data source. Use ACP when you want something outside the agent to control how and where the agent runs. For more on MCP, see the OpenClaw MCP guide.

In a fully built-out setup, both protocols work together: ACP lets an orchestrator drive multiple OpenClaw runtimes across threads, and each runtime uses MCP to call the tools it needs to complete its assigned work.

Which OpenClaw Version Has ACP?

ACP client permission hardening (requiring trusted tool IDs) appeared as a security fix in v2026.2.23. First-class ACP thread-bound agent runtimes and the ACP dispatch system shipped in v2026.2.26, released February 27, 2026. ACP dispatch is enabled by default from that release onward.

If you are running a version earlier than v2026.2.26, you do not have thread-bound ACP runtimes or the agent routing CLI. Upgrading to any release in the 2026.3 or later line gives you ACP along with expanded secrets management and numerous fixes on top.

OpenClaw Launch runs managed instances on a tested, current image. These features are available on every instance without a manual upgrade — if the upstream image has been refreshed to include ACP, your managed instance picks it up automatically.

Getting Started on a Managed Instance

The fastest way to experiment with ACP is on a managed instance where the runtime is already running the right version. You skip the install, the version pinning, and the secrets bootstrap — the gateway is live and ACP dispatch is on by default.

From there you can explore:

The openclaw agents CLI commands to create and inspect thread bindings.
The openclaw secrets workflow to externalize credentials away from inline config.
The acp.dispatch.enabled config field if you need to disable ACP dispatch for a specific deployment.

For exact command signatures and config fields, the OpenClaw GitHub releases page is the authoritative reference. Release notes are detailed and version-specific — worth checking before scripting against any ACP surface in production.