Document ACP orchestration baseline

2026-03-29 23:35:18 -05:00
parent b77134ced5
commit efbdb25937
3 changed files with 230 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -32,6 +32,12 @@ This repository contains practical OpenClaw skills and companion integrations. I
 | `google-maps` | Traffic-aware ETA and leave-by calculations using Google Maps APIs. | `integrations/google-maps` |
 | `google-workspace` | Gmail and Google Calendar helper CLI for profile, mail, attachment-capable send, calendar search, and event creation. | `integrations/google-workspace` |

+## Operator docs
+
+| Doc | What it covers |
+|---|---|
+| `docs/openclaw-acp-orchestration.md` | ACP orchestration setup for Codex and Claude Code on the gateway host |
+
 ## Install ideas

 - Install the whole repo as a skill source.
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,3 +17,7 @@ This folder contains detailed docs for each skill in this repository.

 - [`google-maps`](google-maps.md) — Traffic-aware ETA and leave-by calculations via Google Maps APIs
 - [`google-workspace`](google-workspace.md) — Gmail and Google Calendar helper CLI with attachment-capable send support
+
+## Operator Docs
+
+- [`openclaw-acp-orchestration`](openclaw-acp-orchestration.md) — OpenClaw ACP orchestration for Codex and Claude Code on the gateway host
--- a/docs/openclaw-acp-orchestration.md
+++ b/docs/openclaw-acp-orchestration.md
@@ -0,0 +1,220 @@
+# OpenClaw ACP Orchestration
+
+This document describes the local OpenClaw ACP setup used to orchestrate Codex and Claude Code from an OpenClaw agent on the gateway machine.
+
+## Scope
+
+The target workflow is:
+
+- OpenClaw remains the orchestration brain
+- natural-language requests like `use codex for this` or `run this in claude code` are routed to ACP
+- the coding harness runs on the same gateway machine where the local `codex` and `claude` clients are installed
+- session lifecycle is handled through OpenClaw ACP rather than sub-agents or shell relay hacks
+
+## Local Baseline Before ACP Enablement
+
+Captured on 2026-03-29:
+
+- OpenClaw: `2026.3.28 (f9b1079)`
+- bundled `acpx` plugin present locally but disabled and not in the plugin allowlist
+- local `codex`: `/opt/homebrew/bin/codex` `0.117.0`
+- local `claude`: `/opt/homebrew/bin/claude` `2.1.87`
+- gateway host: 8 CPU cores, 8 GB RAM
+- default OpenClaw agent workspace: `~/.openclaw/workspace`
+
+## Architectural Decision
+
+Primary architecture:
+
+- OpenClaw ACP with `acpx`
+
+Fallback architecture only if parity is not acceptable:
+
+- `openclaw mcp serve` with Codex or Claude Code connected as external MCP clients to existing OpenClaw channel conversations
+
+Why ACP is primary:
+
+- this is the official OpenClaw architecture for "run this in Codex" / "start Claude Code in a thread"
+- it gives durable ACP sessions, resume, bindings, and programmatic `sessions_spawn runtime:"acp"`
+
+## Important Runtime Caveat
+
+The bundled `acpx` runtime supports Codex and Claude, but the stock aliases are adapter commands, not necessarily the bare local terminal binaries:
+
+- `codex -> npx -y @zed-industries/codex-acp@0.9.5`
+- `claude -> npx -y @zed-industries/claude-agent-acp@0.21.0`
+
+That means "same as terminal" behavior has to be validated explicitly. It is not guaranteed just because ACP works.
+
+## Baseline Configuration Applied
+
+The current host-local OpenClaw config keeps the native `main` orchestrator and adds ACP-backed agents alongside it:
+
+- `agents.list[0] = main` with `runtime.type = "embedded"`
+- `agents.list[1] = codex` with `runtime.type = "acp"`
+- `agents.list[2] = claude` with `runtime.type = "acp"`
+- `acp.enabled = true`
+- `acp.dispatch.enabled = true`
+- `acp.backend = "acpx"`
+- `acp.defaultAgent = "codex"`
+- `acp.allowedAgents = ["claude", "codex"]`
+- `acp.maxConcurrentSessions = 2`
+- `plugins.allow += acpx`
+- `plugins.entries.acpx.enabled = true`
+
+The `main` entry is intentional. Once `agents.list` is populated, OpenClaw treats that list as the agent inventory. If `main` is omitted, ACP targets can displace the native orchestrator and break the intended architecture.
+
+## ACP Health Equivalents
+
+The docs mention `/acp doctor`, but the operator-friendly local equivalents on this host are:
+
+- `openclaw config validate`
+- `openclaw plugins inspect acpx --json`
+- `openclaw gateway status --json`
+- `openclaw status --deep`
+- `cd /opt/homebrew/lib/node_modules/openclaw/dist/extensions/acpx && ./node_modules/.bin/acpx config show`
+
+Healthy baseline on this machine means:
+
+- config validates
+- `acpx` plugin status is `loaded`
+- gateway RPC is healthy
+- `openclaw status --deep` shows `Agents 3` with `default main`
+- `acpx config show` works without bootstrap errors
+- `plugins.installs` does not need an `acpx` record because `acpx` is bundled with OpenClaw, not separately installed
+
+## Security Review
+
+### Why this needs a review
+
+ACP coding sessions are headless and non-interactive. If they are allowed to write files and run shell commands, the permission mode matters a lot.
+
+### Leading rollout candidate
+
+- `plugins.entries.acpx.config.permissionMode = "approve-all"`
+- `plugins.entries.acpx.config.nonInteractivePermissions = "deny"`
+
+Why `deny` instead of `fail`:
+
+- on this host, graceful degradation is better than crashing an otherwise useful ACP session at the first blocked headless permission prompt
+- the live `acpx` plugin schema for OpenClaw `2026.3.28` validates `deny`, so this is an intentional runtime choice rather than a placeholder
+
+### What `approve-all` means here
+
+On this gateway host, an ACP coding harness may:
+
+- write files in the configured working tree
+- execute shell commands without an interactive prompt
+- access network resources that are already reachable from the host
+- read local home-directory configuration that the launched harness itself can reach
+
+### Risk boundaries
+
+This host already runs OpenClaw with:
+
+- `tools.exec.host = "gateway"`
+- `tools.exec.security = "full"`
+- `tools.exec.ask = "off"`
+
+So ACP `approve-all` does not create the first fully trusted execution path on this machine. It extends that trust to ACP-backed Codex/Claude sessions. That is still a meaningful trust expansion and should stay limited to trusted operators and trusted channels.
+
+### First-wave rollout stance
+
+Recommended first wave:
+
+- enable ACP only for trusted direct operators
+- prefer explicit `agentId` routing and minimal bindings
+- defer broad persistent group bindings until parity and lifecycle behavior are proven
+- keep the plugin-tools bridge off unless there is a proven need for ACP harnesses to call OpenClaw plugin tools from inside the session
+
+## Observability And Recovery
+
+Minimum required operational checks:
+
+- `openclaw config validate`
+- `openclaw plugins inspect acpx --json`
+- `openclaw gateway status --json`
+- `openclaw status --deep`
+- `openclaw logs --follow`
+- `/tmp/openclaw/openclaw-YYYY-MM-DD.log`
+
+Operational questions this setup must answer:
+
+- did an ACP session start
+- which harness was used
+- which session key is active
+- where a stall or permission denial first occurred
+- whether the gateway restart preserved resumable state
+
+Current host signals:
+
+- plugin status: `openclaw plugins inspect acpx --json`
+- gateway/runtime health: `openclaw gateway status --json`
+- agent inventory and active session count: `openclaw status --deep`
+- ACP adapter defaults and override file discovery: `acpx config show`
+- first runtime failure point: gateway log under `/tmp/openclaw/`
+
+## Concurrency Stance
+
+This machine has 8 CPU cores and 8 GB RAM. A conservative initial ACP concurrency cap is better than the plan's generic placeholder of `8`.
+
+Recommended initial cap:
+
+- `acp.maxConcurrentSessions = 2`
+
+Reason:
+
+- enough for one Codex and one Claude session at the same time
+- low enough to reduce memory pressure and noisy contention on the same laptop-class host
+
+## Plugin Tools Bridge
+
+The planning material discussed `plugins.entries.acpx.config.pluginToolsMcpBridge`, but the local `2026.3.28` bundled `acpx` schema does not currently expose that key in `openclaw plugins inspect acpx --json`.
+
+Current stance:
+
+- treat plugin-tools bridge as unsupported unless the live runtime proves otherwise
+- do not add that key blindly to `openclaw.json`
+
+## Default Workspace Root
+
+The default ACP workspace root for this install is:
+
+- `~/.openclaw/workspace`
+
+Per-session or per-binding `cwd` values can narrow from there when a specific repository or skill workspace is known.
+
+## Rollback
+
+Back up `~/.openclaw/openclaw.json` before any ACP change.
+
+Current ACP implementation backup:
+
+- `~/.openclaw/openclaw.json.bak.pre-acp-implementation-20260329-231818`
+
+Rollback approach:
+
+1. restore the backup config
+2. validate config
+3. restart the gateway
+4. confirm ACP plugin status and channel health
+
+Example rollback:
+
+```bash
+cp ~/.openclaw/openclaw.json.bak.pre-acp-implementation-20260329-231818 ~/.openclaw/openclaw.json
+openclaw config validate
+openclaw gateway restart
+openclaw status --deep
+```
+
+## Implementation Hazards
+
+Two local quirks were discovered during rollout:
+
+- `openclaw config set` is not safe for parallel writes to the same config file. Concurrent `config set` calls can clobber each other.
+- host-local legacy keys can reappear if a write path round-trips older config state. For this rollout, atomic file edits plus explicit validation were safer than chaining many `config set` commands.
+
+## Implementation Notes
+
+This document is updated milestone by milestone as the ACP rollout is implemented and verified.