How to Set Up OpenClaw ACP and Bridge Your IDE to AI Agents

ACP (Agent Client Protocol) is OpenClaw's bridge layer for spawning external coding environments from inside a chat conversation. Instead of switching between OpenClaw and your IDE, ACP lets you start a Claude Code session, a Cursor instance, or a Copilot runtime and interact with it through the same thread where you're already working.

The architecture stacks four layers: a control plane inside OpenClaw, the acpx backend plugin that manages process lifecycle, per-tool adapters that translate between ACP's protocol and each coding tool's native interface, and session management that tracks conversation state across reconnects.

ACP is separate from OpenClaw's built-in code execution. The built-in path runs code inside OpenClaw's managed environment, while ACP delegates work to an external process that runs on your host machine. Choose ACP when you need a specific external tool, like Claude Code or Cursor, rather than the default embedded runtime.

The protocol supports persistent sessions that survive across invocations, named sessions for parallel workstreams, prompt queueing when one task is already running, and session resume for picking up where you left off. If your use crashes, the acpx backend detects the dead process and can reload the session automatically.

ACP supports over a dozen coding uses through built-in adapters. Each use connects through its own authentication path and has different capabilities once spawned.

Claude Code

Uses the Claude Code ACP adapter. Requires host-level Claude Code authentication. Supports session resume natively, so you can disconnect and pick up later with full conversation history.

GitHub Copilot

Connects through the Copilot CLI runtime auth. Good for developers already embedded in the GitHub ecosystem who want Copilot's code suggestions routed through OpenClaw threads.

Cursor

Requires a local Cursor installation. The Cursor CLI ACP adapter bridges between OpenClaw's protocol and Cursor's internal session handling.

Gemini CLI

Uses Gemini CLI authentication or an API key. Useful when you want Google's models for specific tasks while keeping your primary workflow in OpenClaw.

Codex (via ACP)

An explicit fallback for when the native Codex runtime is unavailable. This spawns Codex through the ACP path rather than the embedded runtime.

Additional uses include Factory Droid, OpenCode, Qwen, Pi, iFlow, Kilocode, Kimi, Kiro, Qoder, and Trae. Custom servers also work through the --agent escape hatch in acpx configuration.

When choosing a use, consider three factors: what authentication you already have configured on your machine, which model capabilities you need for the task, and whether you need session resume (currently supported natively by Codex and Claude Code).

Getting ACP running takes three steps: install the acpx plugin, enable it in your OpenClaw config, and verify everything works with the built-in doctor command.

Step 1: Install the acpx plugin

Use the OpenClaw plugin manager to add @openclaw/acpx. This pulls the acpx backend that manages use lifecycle, session state, and prompt routing. The exact install command is in the official ACP docs.

Step 2: Enable the plugin

Toggle acpx to enabled in your OpenClaw plugin configuration. If you run a restrictive plugin inventory, make sure your allow list includes acpx. Otherwise the plugin loads but ACP commands silently fail.

Step 3: Run the doctor check

Type /acp doctor in any OpenClaw conversation. This runs diagnostics against your acpx installation, checks which uses have valid authentication, and flags configuration issues before you try to spawn anything.

Before spawning a specific use, verify that the vendor's authentication exists on your host machine. Claude Code needs its own auth tokens. Copilot needs GitHub CLI authentication. Gemini needs an API key or CLI auth. ACP validates use availability at spawn time, but running doctor first saves you from cryptic error messages.

One gotcha worth knowing: some adapters require npx-based first-run fetches. If you're in an environment without npm or network access, pre-warm the adapter before going offline. Non-interactive sessions also cannot handle native permission prompts, so set permissionMode to approve-all for automated workflows.

Give your ACP harness outputs a persistent home

generous storage with auto-indexing, MCP access, and agent-to-human handoff. No credit card required.

Start 14-Day Trial

ACP offers two ways to connect a use session to your OpenClaw conversation: current-conversation binding and thread-based binding. Which one you choose depends on whether you want a dedicated space for the use or prefer to keep everything in one stream.

Current-conversation binding pins the ACP session to whatever chat surface you're in right now. Run /acp spawn claude --bind here and follow-up messages route directly to that Claude Code session. No child thread gets created. The session stays active until you type /acp close or /unfocus. This works well for quick, focused tasks where you want the use output inline with your conversation.

Thread-based binding creates or attaches to a child thread for the ACP session. Use the --thread flag with three options:

• auto binds to the active thread or creates one when the platform supports it
• here requires an existing thread context
• off disables thread binding entirely

Thread binding is the better choice for longer coding sessions. It keeps the use conversation contained in its own space while your main thread stays clean for coordination and planning.

For Discord and Telegram channels, thread binding needs explicit opt-in. Set channels.discord.threadBindings.spawnSessions=true or the equivalent Telegram setting in your OpenClaw configuration.

You can also set up persistent bindings that survive across sessions. These use a bindings[] array in your config that maps specific channels or peers to use targets. For example, you could permanently bind a Discord channel to a Codex ACP session so that every message in that channel routes to Codex without manual spawning.

Here is the fact that changes how you should think about ACP deployments: ACP sessions run on the host runtime, not inside the OpenClaw sandbox. The official documentation states this explicitly. External uses access files according to their own CLI permissions and your selected working directory, bypassing OpenClaw's sandbox wrapper entirely.

This means a Claude Code session spawned via ACP has the same file access as if you ran Claude Code directly from your terminal. It can read and write files, execute commands, and interact with your system based on Claude Code's own permission model, not OpenClaw's.

OpenClaw still enforces several controls at the protocol level. It validates ACP feature gates before allowing spawn. It checks your acp.allowedAgents list to restrict which uses you can use. Session ownership is verified, channel bindings are enforced, and gateway delivery policy is applied. But none of these controls wrap what the use does once it's running.

What this means in practice:

• Sandboxed requesters cannot spawn ACP sessions at all
• Setting sandbox: "require" is unsupported for runtime: "acp"
• If you need sandbox-enforced code execution, use runtime: "subagent" instead
• For automated or unattended ACP sessions, restricting acp.allowedAgents to only the uses you trust becomes critical
• Setting a runTimeoutSeconds value prevents runaway sessions from accumulating unlimited host access

If you're building multi-agent workflows where agents spawn other agents, this boundary matters even more. An agent that can call sessions_spawn with runtime: "acp" effectively delegates work to a process running outside OpenClaw's security perimeter. Use the acp.allowedAgents allowlist and timeout controls as your primary guardrails.

For workflows where outputs need persistence, audit trails, and controlled handoff, consider routing use results into a workspace platform like Fastio. Agents can write their outputs to shared workspaces where files are versioned, access is controlled with granular permissions, and audit logs track every change. This adds a structured layer around ACP's otherwise open execution model.

Once ACP is configured, day-to-day usage centers on a handful of commands that manage sessions, adjust settings, and control execution.

Spawning a session starts with /acp spawn followed by the use name and any options:

/acp spawn claude --bind here --cwd /path/to/repo

The --cwd flag sets the working directory for the use. Without it, the use inherits whatever directory context acpx determines from your current position.

Checking session status with /acp status shows the active backend, current mode, and available capabilities. This is your first diagnostic step when something feels off.

Switching models mid-session is possible with /acp model. For example, /acp model anthropic/claude-opus-4-6 changes the model without destroying your session state. Note that model IDs are not portable across providers. A model string valid for Claude Code won't work for Gemini.

Canceling work in progress with /acp cancel sends a cooperative cancellation signal. This doesn't destroy the session. The use stops its current task and waits for your next prompt. If you need to end the session entirely, use /acp close.

Setting permissions with /acp permissions strict changes the approval policy for tool use within the use. This is especially relevant for non-interactive deployments where you can't approve each action manually.

Setting timeouts with /acp timeout 120 caps how long a single turn can run before automatic cancellation. Good for preventing runaway tasks in automated pipelines.

For programmatic usage, the sessions_spawn API accepts JSON with parameters like agentId, mode (either "run" for one-shot or "session" for persistent), thread, and resumeSessionId for continuing previous work.

Named sessions with acpx let you run parallel workstreams. From the command line, acpx codex -s backend 'implement pagination' creates a session named "backend" scoped to your current repository. You can have multiple named sessions running simultaneously, each tracking its own conversation history and working directory.

ACP sessions produce code, analysis, and artifacts that often need to outlive the session itself. The use writes files to your local working directory, but for team workflows, you need those outputs somewhere accessible, versioned, and searchable.

Local filesystem storage works for solo development but breaks down when multiple people or agents need access to the same artifacts. Git solves the versioning problem but adds friction for non-code outputs like reports, analysis documents, and generated assets.

Cloud storage services like Google Drive, Dropbox, or S3 provide accessibility but lack the agent-aware features that make handoff smooth. You end up building custom scripts to sync files, manage permissions, and track what each agent produced.

Fastio fits this gap as a workspace platform designed for agent-to-human handoff. When an ACP use generates files, you can push them to a Fastio workspace where they're automatically indexed for semantic search through Intelligence Mode. The MCP server exposes workspace operations through Streamable HTTP, so agents can upload, organize, and share outputs programmatically.

The practical workflow looks like this: your ACP use writes code or generates a report. A follow-up step pushes the output to a Fastio workspace using the API or MCP tools. The workspace versions the file, indexes it for search, and makes it available to teammates through the web interface or branded shares. When the project is ready, ownership transfer moves the entire workspace from the agent account to a human, with the agent retaining admin access for future updates.

The Business Trial includes 50 GB of storage, included credits, and 5 workspaces with no credit card required. For teams running multiple ACP uses that produce artifacts daily, this provides a persistent layer that doesn't depend on any single developer's local machine.