ACP agents
Agent Client Protocol (ACP) sessions let WednesdayAI run external coding harnesses (for example Pi, Claude Code, Codex, OpenCode, and Gemini CLI) through an ACP backend plugin. If you ask WednesdayAI in plain language to “run this in Codex” or “start Claude Code in a thread”, WednesdayAI should route that request to the ACP runtime (not the native sub-agent runtime).Fast operator flow
Use this when you want a practical/acp runbook:
- Spawn a session:
/acp spawn codex --mode persistent --thread auto
- Work in the bound thread (or target that session key explicitly).
- Check runtime state:
/acp status
- Tune runtime options as needed:
/acp model <provider/model>/acp permissions <profile>/acp timeout <seconds>
- Nudge an active session without replacing context:
/acp steer tighten logging and continue
- Stop work:
/acp cancel(stop current turn), or/acp close(close session + remove bindings)
Quick start for humans
Examples of natural requests:- “Start a persistent Codex session in a thread here and keep it focused.”
- “Run this as a one-shot Claude Code ACP session and summarize the result.”
- “Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread.”
- Pick
runtime: "acp". - Resolve the requested harness target (
agentId, for examplecodex). - If thread binding is requested and the current channel supports it, bind the ACP session to the thread.
- Route follow-up thread messages to that same ACP session until unfocused/closed/expired.
ACP versus sub-agents
Use ACP when you want an external harness runtime. Use sub-agents when you want WednesdayAI-native delegated runs.
See also Sub-agents.
Thread-bound sessions (channel-agnostic)
When thread bindings are enabled for a channel adapter, ACP sessions can be bound to threads:- WednesdayAI binds a thread to a target ACP session.
- Follow-up messages in that thread route to the bound ACP session.
- ACP output is delivered back to the same thread.
- Unfocus/close/archive/idle-timeout or max-age expiry removes the binding.
acp.enabled=trueacp.dispatch.enabledis on by default (setfalseto pause ACP dispatch)- Channel-adapter ACP thread-spawn flag enabled (adapter-specific)
- Discord:
channels.discord.threadBindings.spawnAcpSessions=true
- Discord:
Thread supporting channels
- Any channel adapter that exposes session/thread binding capability.
- Current built-in support: Discord.
- Plugin channels can add support through the same binding interface.
Start ACP sessions (interfaces)
From sessions_spawn
Use runtime: "acp" to start an ACP session from an agent turn or tool call.
runtimedefaults tosubagent, so setruntime: "acp"explicitly for ACP sessions.- If
agentIdis omitted, WednesdayAI usesacp.defaultAgentwhen configured. mode: "session"requiresthread: trueto keep a persistent bound conversation.mode: "run"children do not post their output to the channel. When the run ends, the requesting agent receives atask_completionevent with the result and writes the reply (defaultcompletionDelivery: "parent"; see Sub-agents). Run-mode children show up insubagents list, andsubagents killor/stopalso cancels the ACP turn.
task(required): initial prompt sent to the ACP session.runtime(required for ACP): must be"acp".agentId(optional): ACP target harness id. Falls back toacp.defaultAgentif set.thread(optional, defaultfalse): request thread binding flow where supported.mode(optional):run(one-shot) orsession(persistent).- default is
run - if
thread: trueand mode omitted, WednesdayAI may default to persistent behavior per runtime path mode: "session"requiresthread: true
- default is
cwd(optional): requested runtime working directory (validated by backend/runtime policy).label(optional): operator-facing label used in session/banner text.completionDelivery(optional,mode: "run"only):"parent"(default) hands the result to the requesting agent;"direct"sends it straight to the requester chat. See Completion delivery.
Sandbox compatibility
ACP sessions currently run on the host runtime, not inside the WednesdayAI sandbox. Current limitations:- If the requester session is sandboxed, ACP spawns are blocked.
- Error:
Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
- Error:
sessions_spawnwithruntime: "acp"does not supportsandbox: "require".- Error:
sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".
- Error:
runtime: "subagent" when you need sandbox-enforced execution.
From /acp command
Use /acp spawn for explicit operator control from chat when needed.
--mode persistent|oneshot--thread auto|here|off--cwd <absolute-path>--label <name>
Session target resolution
Most/acp actions accept an optional session target (session-key, session-id, or session-label).
Resolution order:
- Explicit target argument (or
--sessionfor/acp steer)- tries key
- then UUID-shaped session id
- then label
- Current thread binding (if this conversation/thread is bound to an ACP session)
- Current requester session fallback
Unable to resolve session target: ...).
Spawn thread modes
/acp spawn supports --thread auto|here|off.
Notes:
- On non-thread binding surfaces, default behavior is effectively
off. - Thread-bound spawn requires channel policy support (for Discord:
channels.discord.threadBindings.spawnAcpSessions=true).
ACP controls
Available command family:/acp spawn/acp cancel/acp steer/acp close/acp status/acp set-mode/acp set/acp cwd/acp permissions/acp timeout/acp model/acp reset-options/acp sessions/acp doctor/acp install
/acp status shows the effective runtime options and, when available, both runtime-level and backend-level session identifiers.
Some controls depend on backend capabilities. If a backend does not support a control, WednesdayAI returns a clear unsupported-control error.
ACP command cookbook
Runtime options mapping
/acp has convenience commands and a generic setter.
Equivalent operations:
/acp model <id>maps to runtime config keymodel./acp permissions <profile>maps to runtime config keyapproval_policy./acp timeout <seconds>maps to runtime config keytimeout./acp cwd <path>updates runtime cwd override directly./acp set <key> <value>is the generic path.- Special case:
key=cwduses the cwd override path.
- Special case:
/acp reset-optionsclears all runtime overrides for target session.
acpx harness support (current)
Current acpx built-in harness aliases:piclaudecodexopencodegeminikimi
agentId unless your acpx config defines custom agent aliases.
Direct acpx CLI usage can also target arbitrary adapters via --agent <command>, but that raw escape hatch is an acpx CLI feature (not the normal WednesdayAI agentId path).
Required config
Core ACP baseline:- Discord:
channels.discord.threadBindings.spawnAcpSessions=true
Plugin setup for acpx backend
Install and enable plugin:acpx command and version configuration
By default, the acpx plugin (published as@openclaw/acpx) uses the plugin-local pinned binary:
- Command defaults to
extensions/acpx/node_modules/.bin/acpx. - Expected version defaults to the exact
acpxversion in the plugin’spackage.json(dependencies.acpx). - Startup registers ACP backend immediately as not-ready.
- A background ensure job verifies
acpx --version. - If the plugin-local binary is missing or mismatched, it runs:
npm install --omit=dev --no-save acpx@<pinned>and re-verifies.
commandaccepts an absolute path, relative path, or command name (acpx).- Relative paths resolve from WednesdayAI workspace directory.
expectedVersion: "any"disables strict version matching.- When
commandpoints to a custom binary/path, plugin-local auto-install is disabled. - WednesdayAI startup remains non-blocking while the backend health check runs.
Upgrading from acpx 0.1.x
- Persistent ACP sessions created under 0.1.x start a new acpx session on their next use, and the agent’s earlier conversation history is not carried over. acpx matches sessions by their exact adapter command, and the default adapters changed (codex →
@agentclientprotocol/codex-acp, claude →@agentclientprotocol/claude-agent-acp, gemini →gemini --acp). WednesdayAI re-resolves the session identities automatically at gateway startup. - Claude sessions no longer load user-level Claude settings (
~/.claude/settings.json). To restore them, setACPX_CLAUDE_INCLUDE_USER_SETTINGS=1in the gateway’s environment; spawned acpx processes inherit it. - ACP adapter authentication no longer picks up ambient API keys such as
OPENAI_API_KEY. SetACPX_AUTH_<METHOD_ID>(for exampleACPX_AUTH_OPENAI_API_KEY) when an adapter needs ACP-level auth. - Session status reports
idle, notdead, for a resumable session with no running process. - The first prompt after the upgrade downloads the new adapter through
npx, so it takes noticeably longer.
Permission configuration
ACP sessions run non-interactively — there is no TTY to approve or deny file-write and shell-exec permission prompts. The acpx plugin provides two config keys that control how permissions are handled:permissionMode
Controls which operations the harness agent can perform without prompting.
nonInteractivePermissions
Controls what happens when a permission prompt would be shown but no interactive TTY is available (which is always the case for ACP sessions).
Configuration
Set via plugin config:Important: WednesdayAI currently defaults topermissionMode=approve-readsandnonInteractivePermissions=fail. In non-interactive ACP sessions, any write or exec that triggers a permission prompt can fail withAcpRuntimeError: Permission prompt unavailable in non-interactive mode. If you need to restrict permissions, setnonInteractivePermissionstodenyso sessions degrade gracefully instead of crashing.
Gateway restarts
ACP turns survive a gateway restart by state, not by process. Each turn is recorded as akind: "acp" session run, so a restart or stop never silently loses one.
What you see as a user:
-
If the gateway restarts or stops while an ACP turn is running, the turn is cancelled and the bound thread receives one notice:
- Commands or edits the harness already started may still have completed even though no final reply arrived. Treat any partial output as a side effect that happened, and review the workspace before re-asking.
-
Messages sent while the gateway is restarting never reach the agent, so nothing ran and there are no side effects. The gateway refuses new messages as soon as the restart drain begins, so you may get no reply at all, or an
ACP_GATEWAY_DRAININGerror for a message that arrived just as the drain started. Either way, resend it after the gateway is back. - If the gateway crashes instead of restarting cleanly, or the notice could not be delivered during the shutdown (this includes turns started by a spawned agent task rather than a message in the thread), the same notice is delivered at the next boot. Once the notice reaches you it is not repeated; if the gateway still could not deliver it (for example the chat channel was still coming back online), it tries again later instead of skipping you.
-
A run-mode child (
sessions_spawnwithmode: "run") has no thread of its own. If the gateway restarts during its turn, the requesting agent is told the child ended with an error.
/acp status shows the same agentSessionId. sessions.runs.continue does not apply to ACP turns: continuation is by replying in the bound thread, not through that RPC.