/acpx-faq

name: acpx-faq
description: Run coding agents (codex, claude, agy) through the acpx ACP CLI - one-shot dispatch into named sessions you can watch live. Use before launching or prompting a subagent, or when a command fails, a session is missing, or a prompt is lost.
metadata:
  version: "0.11.0"
  categories: "agents, operations"
  topics: "acpx, acp, agent-orchestration, troubleshooting, headless-agents"
  upstream: "acpx@0.21.1, @agentclientprotocol/claude-agent-acp@0.100.0, @agentclientprotocol/codex-acp@2.5.0, agy@1.5.0, agy_acp_server@1.4.5"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/acpx-faq
    emoji: "🔌"

acpx FAQ

Drive coding agents headlessly through [acpx](https://github.com/openclaw/acpx) (>= 0.19.3).

Syntax authority

Syntax comes from the binary, not this file. `acpx --skill show acpx` is the vendor reference (~43k chars) and the tiebreaker on command shape - do NOT dump it into the transcript. Retrieve in this order:

1. `acpx --help` / `acpx <cmd> --help` - the flags you are about to compose. 2. One topic: `acpx --skill show acpx | rg -B2 -A12 '<term>'`, or a section: `acpx --skill show acpx | sed -n '/^## Sessions/,/^## /p'`. 3. Authoring something novel (a flow, an embedded runtime): dump ONCE to a scratch file and grep that file.

This file repeats nothing the reference covers. It carries only what the reference lacks: exit codes, failure semantics, traps, and per-agent recipes. If a syntax question is not answered here, it is answered there - go get it, never guess a flag. The repo's `docs/` (exit-codes, session-control, session-watch, permissions, config) cover some of what the shipped reference omits.

When this lane

acpx is the headless out-of-process executor lane: another agent, vendor or account, driven from a script or from another agent, in a plain terminal, ssh or cron. In-session fan-out stays on the harness's own subagent tool.

Invariants

1. **Global flags precede the agent subcommand** (`--cwd`, `--model`, `--approve-all`, `--agent`, `--format`, `--timeout`, `--ttl`, `--mcp-config`). The prompt form accepts only `-s`, `--no-wait`, `-f` (and `exec` also `--config-option`); other subcommands carry their own (`sessions watch --cursor`, `sessions export|import --cwd`). A global flag after the agent exits **1** with `error: unknown option`; a bad flag *before* the agent exits **2**. 2. **`-s <name>` never creates a session.** It resolves one, walking from `--cwd` up to the nearest `.git` - a directory *or file*, so each worktree and submodule is its own boundary; outside git only the exact `--cwd` is checked. No match exits **4**. Create first with `sessions ensure --name <n>` in the same directory. 3. **`status` is not a turn signal.** It probes the queue-owner process, never the agent, and keeps saying `running` after the turn has ended. Never gate automation on it. 4. **Permission flags are not a sandbox.**

• **claude**: the adapter starts in `permissions.defaultMode` from the Claude

settings (`acceptEdits` / `auto` approve edits without asking). Only what that mode escalates reaches acpx as a permission request - `--deny-all` refuses those (exit 5), but an auto-approved edit never asks.

• **codex**: writes inside its workspace-write sandbox (rooted at `--cwd`, plus temp

dirs) raise no request, so `--deny-all` still writes; outside fails with `Operation not permitted` - including a linked worktree's gitdir, so a sandboxed lane in a `git worktree` cannot commit (`index.lock: Operation not permitted`). Network is off unless `config.toml` enables `network_access`. `--approve-all` does not change the adapter's mode; `INITIAL_AGENT_MODE=read-only|agent|agent-full-access` at spawn, or `codex set-mode agent-full-access -s <n>` on a live session, does.

• `--allowed-tools` / `--max-turns` reach only claude (and qoder); codex and agy

ignore them. `--allowed-tools` pre-approves and never restricts: `--help`'s `"" for no tools` means no approvals, not no tools.

The real filesystem control is which `--cwd` you hand it. 5. **`[done] end_turn` and exit 0 are not proof of success.** A content-filter kill, an MCP load failure, an API error (a 401 during a token refresh, a 400 model rejection), or a truncated turn all end that way. Read the stream, or require the agent to write a result file you can check. Before a fan-out, one cheap `exec` ("Reply OK") per agent and model catches auth and model errors - codex and agy reject an unadvertised `--model` before the turn, claude warns and forwards it. 6. **A persistent session holds a resident process stack only while it is busy or warm.** Every `-s` prompt elects a queue owner holding `npm exec -> node <adapter> -> <agent>` (plus the agent's MCP servers), roughly 550-650 MB before MCP. After the idle TTL (default 300s) the owner exits and the session stays resumable; the next prompt respawns it. `sessions close` ends the task - chain it into the launch line (see Per agent) so teardown never depends on anyone remembering; `--ttl 0` removes the self-reap. See Teardown.

Per agent

**Dispatch one-shot: `sessions ensure && prompt && sessions close`, one chained call.** One named session per task, one prompt, closed when the result file is read. The `&&` chain makes teardown mechanical - nothing reaps open records, and orphans come from unchained closes - while a turn that fails nonzero (timeout 3, permission 5) skips the close on its own, leaving the session open for recovery (see Talking to a live session). An externally cancelled turn still exits 0, so the result file, not the exit code, is the success check (invariant 5). Do not park a session for expected follow-ups: a blocker's state lives outside the conversation (creds are machine-level, partials belong in the result file) - answer it with a fresh session fed the brief plus that fil