acpx-faq

# acpx FAQ Drive coding agents headlessly through [acpx](https://github.com/openclaw/acpx) (>= 0.15.1). Command syntax: `acpx --skill show acpx` - the binary ships its own reference and is the tiebreaker on syntax. That doc is strong on command shape and silent on failure semantics: it has no exit-code table, no `status` state table, and does not mention `--mcp-config` at all. This file is the other half. Read the Invariants, then your agent's section in **Per agent** - each is a complete launch-to-result recipe. After that: Sessions, Completion, MCP, Limits, Failures. ## Invariants 1. **Global flags precede the agent subcommand.** `--cwd`, `--model`, `--approve-all`, `--agent`, `--format`, `--timeout`, `--ttl`, `--mcp-config` are all global. The subcommand accepts only `-s`, `--no-wait`, `-f` (and `exec` also takes `--config-option`). Putting a global flag after the agent exits **2** with `error: unknown option '--cwd'`. 2. **`-s <name>` never creates a session.** It resolves one, walking from `--cwd` up to the git root. No match exits **4**. Create first with `sessions ensure --name <n>`. 3. **`status` is not a turn signal.** It reports the queue-owner process, not the turn, and keeps saying `running` after the turn has ended. Never gate automation on it. 4. **Permission flags only gate requests the adapter chooses to raise.** The claude adapter spawns its binary with `--allow-dangerously-skip-permissions --setting-sources=project,local`, so it neve...