mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 14:30:45 +00:00
feat(acp): add opt-in Coven runtime bridge
Add the opt-in Coven ACP runtime bridge as a bundled extension while keeping ACPX as the default path.
Security hardening included before merge:
- fail closed by default instead of silently falling back;
- bounded health/socket requests and daemon response sizes;
- fixed Coven socket trust anchor and symlink/path validation;
- reject untrusted harness/session/event ids before exposing them;
- sanitize daemon-controlled terminal/status/error strings;
- use incremental event polling with bounded dedupe state;
- clean up launched Coven sessions before fallback when daemon ids are invalid.
Validation:
- pnpm test extensions/coven/src/config.test.ts extensions/coven/src/client.test.ts extensions/coven/src/runtime.test.ts
- pnpm check:changed
- GitHub CI green on a64eac20b9
- Greptile Review green
This commit is contained in:
@@ -186,6 +186,77 @@ Override the command or version in plugin config:
|
||||
|
||||
See [Plugins](/tools/plugin).
|
||||
|
||||
## Optional Coven backend
|
||||
|
||||
OpenClaw can also register a bundled, opt-in `coven` ACP backend for operators
|
||||
who want ACP coding sessions supervised by a local [Coven](https://github.com/OpenCoven/coven)
|
||||
daemon instead of launched directly through ACPX.
|
||||
|
||||
This is intentionally an extension, not a core runtime path:
|
||||
|
||||
- the default ACPX backend stays unchanged for normal installs;
|
||||
- Coven has its own daemon, socket, session store, harness mapping, and project
|
||||
boundary model;
|
||||
- the bridge can be enabled, disabled, configured, and reviewed independently
|
||||
through the plugin system; and
|
||||
- OpenClaw remains responsible for ACP session routing, chat bindings, task
|
||||
state, and fallback policy while Coven owns harness supervision.
|
||||
|
||||
Minimal opt-in config:
|
||||
|
||||
```json5
|
||||
{
|
||||
acp: {
|
||||
enabled: true,
|
||||
backend: "coven",
|
||||
defaultAgent: "codex",
|
||||
},
|
||||
plugins: {
|
||||
entries: {
|
||||
coven: {
|
||||
enabled: true,
|
||||
config: {
|
||||
// Optional. Defaults to ~/.coven. Environment variables are not used for this trust anchor.
|
||||
covenHome: "~/.coven",
|
||||
// Optional. Defaults to <covenHome>/coven.sock; overrides must resolve to that path.
|
||||
socketPath: "~/.coven/coven.sock",
|
||||
// Optional. Defaults to false; enable only when direct ACP fallback is acceptable.
|
||||
allowFallback: false,
|
||||
// Optional. Used only when allowFallback is true.
|
||||
fallbackBackend: "acpx",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
When selected, OpenClaw checks Coven daemon health over the configured Unix
|
||||
socket before launching. A successful launch creates a Coven session and records
|
||||
the Coven session id in the ACP runtime handle. If the health check or launch
|
||||
fails, OpenClaw fails closed by default so `acp.backend="coven"` cannot silently
|
||||
downgrade to direct ACP execution. Set `allowFallback: true` only when direct
|
||||
ACP fallback is an explicit, acceptable operator choice.
|
||||
|
||||
For path safety, `~` in `covenHome` and `socketPath` expands to the current
|
||||
user home directory, and configured Coven paths must be absolute after that
|
||||
expansion. OpenClaw rejects workspace-relative Coven daemon paths because the
|
||||
daemon socket is a local user trust anchor, not repository-controlled state.
|
||||
`socketPath` must resolve to `<covenHome>/coven.sock`; OpenClaw does not allow
|
||||
arbitrary Coven socket filenames because the daemon socket is the local trust
|
||||
anchor. Keep `covenHome` owned by the OpenClaw user and private (`0700`);
|
||||
OpenClaw rejects symlinked, shared-accessible, shared-writable, or non-socket
|
||||
Coven socket paths before connecting. The Coven backend currently requires Unix
|
||||
socket validation and fails closed on Windows rather than trusting a socket path
|
||||
whose owner and permissions cannot be validated by this plugin.
|
||||
|
||||
The default harness mapping sends known ACP agent ids such as `codex`, `claude`,
|
||||
`gemini`, and `opencode` to explicitly authorized Coven harness ids. Unknown
|
||||
ACP agent ids are rejected instead of being forwarded as harness names. Override
|
||||
`plugins.entries.coven.config.harnesses` only when your local Coven install uses
|
||||
custom harness names, and keep `acp.allowedAgents` aligned with the intended
|
||||
chat-exposed harness set.
|
||||
|
||||
### Automatic dependency install
|
||||
|
||||
When you install OpenClaw globally with `npm install -g openclaw`, the acpx
|
||||
|
||||
Reference in New Issue
Block a user