/acpx-faq

name: acpx-faq
description: Run coding agents (codex, claude, agy/Antigravity) through the acpx ACP CLI - the headless lane outside a herdr pane (no HERDR_ENV). Use before launching or prompting a subagent, and when a command fails, a session is not found, or a prompt is lost.
metadata:
  version: "0.5.1"
  categories: "agents, operations"
  topics: "acpx, acp, agent-orchestration, troubleshooting, headless-agents"
  upstream: "acpx@0.15.1, agy@1.1.28, agy_acp_server@20260818_01_RC01"
  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.15.1).

Syntax authority

Syntax comes from the binary, not this file. `acpx --skill show acpx` is the vendor reference (~29k 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.

When this lane

acpx is the headless out-of-process executor lane. Inside a herdr pane (`HERDR_ENV=1`) prefer herdr (herdr-faq): it gives you screen reads and dialog detection. Everywhere else (plain terminal, ssh, cron) herdr is untargetable and acpx is the lane. 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 subcommand accepts only `-s`, `--no-wait`, `-f` (and `exec` also `--config-option`). A global flag after the agent exits **2** with `error: unknown option`. 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 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.** The claude adapter spawns its binary with `--allow-dangerously-skip-permissions --setting-sources=project,local`, so no permission request ever reaches acpx's policy layer (`--deny-all` is unreachable, not ignored); codex writes through its terminal capability. `--no-terminal` genuinely removes the terminal capability, but the only real filesystem control is which `--cwd` you hand it. Verify: `ps -Ao args | grep claude-agent-sdk` mid-turn. 5. **`[done] end_turn` and exit 0 are not proof of success.** A content-filter kill, an MCP load failure, or a truncated turn all end that way. Read the stream, or require the agent to write a result file you can check. 6. **A persistent session leaves a resident process stack until you close it.** Every `-s` prompt elects a queue owner holding `npm exec -> node <adapter> -> <agent>`, roughly 700 MB per executor. `sessions close` is the only supported teardown; the idle TTL (default 300s) is the backstop, and `--ttl 0` removes it. See Teardown.

Per agent

**Default to `exec` for dispatched work.** `exec` runs a temporary session: no saved record, not queue-aware, so it never elects a queue owner and leaves nothing to clean up. Use `-s <name>` only to queue follow-ups onto a live run or to read `sessions history` afterwards - and then the closing `sessions close` is part of the recipe (invariant 6). One directory (ideally one worktree) per parallel executor: sessions key on cwd.

agy / Antigravity - the `--agent` escape hatch

**acpx has no Antigravity adapter**, and the built-in `gemini` agent is the *public Gemini CLI* - a different product, dead for Code Assist. The only route is Google's signed ACP server via `--agent`: the `.par` installed by Antigravity under `~/.local/lib/antigravity-acp/` (if missing, install Antigravity - never download it). `localharness_external` beside it must stay executable, or the server starts anyway and only logs `Localharness not found`.

# macOS: --agent may point straight at the .par
D=/abs/real/dir                              # must exist: roots resolve through realpath
acpx --agent ~/.local/lib/antigravity-acp/agy_acp_server.par \
     --cwd "$D" --model gemini-3.7-flash-medium --timeout 1800 \
     exec 'Carry out $D/brief.md. Write your report to $D/report.md.'

• **Default `gemini-3.7-flash-medium`** (measured on par with Opus for rubric-driven

bulk work and far faster; `gemini-3.8-flash-high` measured worse on the same task). Effort lives in the model id (`gemini-3.7-flash-{low,medium,high}`); no separate knob.

• **agy reads sibling files unprompted** - agents sharing a directory reproduce each

other's output. One directory per agent, and checksum any rerun before believing an agreement number.

• **Auth: with no auth type configured the server hangs on `authenticate` forever** -

it reads exactly like a network stall. One-time fix:

  mkdir -p ~/.gemini/antigravity-acp
  echo '{"auth":{"type":"oauth-personal"}}' > ~/.gemini/antigravity-acp/settings.json

then complete its own sign-in once; the token persists. The server reads `~/.gemini/antigravity-acp/acp_token.json`, never the CLI's token - a fully authenticated `agy` does nothing for this lane, and `GEMINI_HOME` relocates the whole tree (a second isolated lane). An entitlement problem is server-side with no client lever - do not "fix" it by switching t