From efbdb25937e6d01e858e569a694ae5efa1a46578 Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Sun, 29 Mar 2026 23:35:18 -0500 Subject: [PATCH] Document ACP orchestration baseline --- README.md | 6 + docs/README.md | 4 + docs/openclaw-acp-orchestration.md | 220 +++++++++++++++++++++++++++++ 3 files changed, 230 insertions(+) create mode 100644 docs/openclaw-acp-orchestration.md diff --git a/README.md b/README.md index 50d7ede..214e13f 100644 --- 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. diff --git a/docs/README.md b/docs/README.md index 125d471..dd370cd 100644 --- 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 diff --git a/docs/openclaw-acp-orchestration.md b/docs/openclaw-acp-orchestration.md new file mode 100644 index 0000000..a6f0a39 --- /dev/null +++ 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.