# OpenClaw ACP Agents
[[Agent Client Protocol (ACP)|ACP]] sessions let [[OpenClaw]] spawn external coding harnesses as managed sessions. Where [[OpenClaw Sub-Agents|sub-agents]] are *OpenClaw* instances doing background work, ACP sessions are *third-party* coding agents (Claude Code, Codex, etc.) running under OpenClaw's session lifecycle and approval rules.
This is the bridge that turns OpenClaw into a multi-harness orchestrator: the main agent reasons in chat, but when real coding work is needed, it dispatches to a specialized harness via ACP.
## Supported Harnesses
Spawnable via the `acpx` backend plugin:
- [[Pi Mono|Pi]] (default in many setups)
- [[Claude Code]]
- [[OpenAI Codex|Codex]]
- OpenCode
- [[Gemini CLI]]
- [[Kimi Code|Kimi]]
## Configuration
```json
{
"acp": {
"enabled": true,
"backend": "acpx",
"defaultAgent": "codex",
"allowedAgents": ["pi", "claude", "codex", "opencode", "gemini", "kimi"]
}
}
```
Install with:
```bash
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
```
## Session Lifecycle
Key slash commands:
- `/acp spawn <agent>` ; create and optionally bind a session
- `--mode persistent|oneshot`
- `--thread auto|here|off` (Discord/Telegram only)
- `/acp status` ; backend, mode, state, capabilities
- `/acp steer <msg>` ; guide without replacing context
- `/acp cancel` ; stop current work
- `/acp close` ; terminate session
- `/acp model` / `/acp permissions` / `/acp timeout` ; runtime tuning
- `/acp doctor` ; backend health check
## Permission Model
ACP sessions run on the **host runtime**, not in a sandbox ; they need filesystem and shell access to actually code. Because no TTY exists for interactive prompts, permissions are preset:
- `approve-all` ; trust everything (dangerous)
- `approve-reads` (default) ; reads ok, writes/exec require explicit approval
- `deny-all` ; for diagnostic sessions
Choose deliberately ; this is the boundary that decides whether an ACP harness can clobber files.
## Thread Binding
On Discord and Telegram, an ACP session can be thread-bound so the harness's output stays in a dedicated thread instead of polluting the main channel. Combined with `--mode persistent`, this gives a long-lived "Claude Code in this thread" experience.
## References
- ACP Agents: https://docs.openclaw.ai/tools/acp-agents
## Related
- [[OpenClaw]]
- [[OpenClaw Sub-Agents]]
- [[Agent Client Protocol (ACP)]]
- [[Claude Code]]
- [[OpenAI Codex]]
- [[Gemini CLI]]
- [[Pi Mono]]
- [[AI Agent Harness]]