@enderfga/claw-orchestrator 7.13.0 → 7.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -11
- package/configs/engines/README.md +20 -0
- package/configs/engines/dsh.json +17 -0
- package/configs/engines/kimi-code.json +17 -0
- package/dist/bin/cli.js +57 -28
- package/dist/bin/cli.js.map +1 -1
- package/dist/src/acp-server.js +4 -2
- package/dist/src/acp-server.js.map +1 -1
- package/dist/src/embedded-server.js +7 -2
- package/dist/src/embedded-server.js.map +1 -1
- package/dist/src/engine-presets.d.ts +7 -3
- package/dist/src/engine-presets.js +39 -6
- package/dist/src/engine-presets.js.map +1 -1
- package/dist/src/index.js +20 -2
- package/dist/src/index.js.map +1 -1
- package/dist/src/persistent-acp-session.d.ts +76 -0
- package/dist/src/persistent-acp-session.js +409 -0
- package/dist/src/persistent-acp-session.js.map +1 -0
- package/dist/src/session-manager.js +9 -0
- package/dist/src/session-manager.js.map +1 -1
- package/dist/src/types.d.ts +29 -1
- package/dist/src/types.js +2 -0
- package/dist/src/types.js.map +1 -1
- package/openclaw.plugin.json +1 -1
- package/package.json +2 -2
- package/skills/SKILL.md +1 -1
- package/skills/references/acp.md +4 -0
- package/skills/references/claude-cli-tracking.md +2 -1
- package/skills/references/cli.md +47 -38
- package/skills/references/multi-engine.md +20 -0
- package/skills/references/tools.md +52 -51
package/dist/src/types.d.ts
CHANGED
|
@@ -8,7 +8,7 @@ export declare const MODEL_ALIASES: Record<string, string>;
|
|
|
8
8
|
export type PermissionMode = 'acceptEdits' | 'bypassPermissions' | 'default' | 'manual' | 'dontAsk' | 'plan' | 'auto';
|
|
9
9
|
export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max", "ultra", "auto"];
|
|
10
10
|
export type EffortLevel = (typeof EFFORT_LEVELS)[number];
|
|
11
|
-
export declare const ENGINE_TYPES: readonly ["claude", "codex", "codex-app", "gemini", "agy", "cursor", "grok", "opencode", "custom"];
|
|
11
|
+
export declare const ENGINE_TYPES: readonly ["claude", "codex", "codex-app", "gemini", "agy", "cursor", "grok", "opencode", "custom", "acp"];
|
|
12
12
|
export type EngineType = (typeof ENGINE_TYPES)[number];
|
|
13
13
|
/** Common execution binding shared by every directly configured agent. */
|
|
14
14
|
export interface AgentBinding {
|
|
@@ -159,6 +159,26 @@ export interface CustomEngineConfig {
|
|
|
159
159
|
*/
|
|
160
160
|
sanitizePatterns?: string[];
|
|
161
161
|
}
|
|
162
|
+
export interface AcpAgentConfig {
|
|
163
|
+
/** Display name (logs, session ids). */
|
|
164
|
+
name: string;
|
|
165
|
+
/** Command name or path that serves ACP on stdio, e.g. 'kimi'. */
|
|
166
|
+
command: string;
|
|
167
|
+
/** Environment variable that overrides `command` at runtime, e.g. 'KIMI_BIN'. */
|
|
168
|
+
commandEnv?: string;
|
|
169
|
+
/** Arguments after the command, e.g. ['acp']. */
|
|
170
|
+
args?: string[];
|
|
171
|
+
/** Extra environment for the process. */
|
|
172
|
+
env?: Record<string, string>;
|
|
173
|
+
/** Context window in tokens, when the agent does not report one. */
|
|
174
|
+
contextWindow?: number;
|
|
175
|
+
/** Price per million tokens, used only when the agent reports no cost. */
|
|
176
|
+
pricing?: {
|
|
177
|
+
input: number;
|
|
178
|
+
output: number;
|
|
179
|
+
cached?: number;
|
|
180
|
+
};
|
|
181
|
+
}
|
|
162
182
|
/**
|
|
163
183
|
* One entry of Claude Code's `--agents` JSON, passed to the CLI verbatim.
|
|
164
184
|
*
|
|
@@ -364,6 +384,12 @@ export interface SessionConfig {
|
|
|
364
384
|
* `src/engine-presets.ts` for what a preset promises and what it does not.
|
|
365
385
|
*/
|
|
366
386
|
customEngine?: CustomEngineConfig | string;
|
|
387
|
+
/**
|
|
388
|
+
* The agent to run — required when engine is 'acp'. An inline config, or the
|
|
389
|
+
* id of a bundled preset from `configs/engines/` (the only form accepted over
|
|
390
|
+
* HTTP, as for `customEngine`).
|
|
391
|
+
*/
|
|
392
|
+
acpAgent?: AcpAgentConfig | string;
|
|
367
393
|
}
|
|
368
394
|
export interface SessionStats {
|
|
369
395
|
/**
|
|
@@ -443,6 +469,8 @@ export interface SessionStats {
|
|
|
443
469
|
opencodeSessionId?: string;
|
|
444
470
|
/** Grok Build session ID captured from the turn's JSON result. Reused via `--resume` for multi-turn context. */
|
|
445
471
|
grokSessionId?: string;
|
|
472
|
+
/** ACP session id from `session/new`; a later session loads it with `session/load` or `session/resume`. */
|
|
473
|
+
acpSessionId?: string;
|
|
446
474
|
/**
|
|
447
475
|
* True when the most recent turn's token counts came from estimateTokens()
|
|
448
476
|
* because the engine reported no usage. Cost derived from those counts is an
|
package/dist/src/types.js
CHANGED
|
@@ -22,6 +22,7 @@ export const ENGINE_TYPES = [
|
|
|
22
22
|
'grok',
|
|
23
23
|
'opencode',
|
|
24
24
|
'custom',
|
|
25
|
+
'acp',
|
|
25
26
|
];
|
|
26
27
|
/**
|
|
27
28
|
* The executables the built-in engines actually spawn — the defaults in each
|
|
@@ -70,6 +71,7 @@ export function engineHasNativeConversation(engine, customEngine) {
|
|
|
70
71
|
case 'opencode':
|
|
71
72
|
case 'cursor':
|
|
72
73
|
case 'grok':
|
|
74
|
+
case 'acp':
|
|
73
75
|
return true;
|
|
74
76
|
case 'custom':
|
|
75
77
|
// A persistent custom engine is a long-running stdin/stdout process, so it
|
package/dist/src/types.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAA2B,UAAU,EAAE,CAAC;AAUlE,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAC9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAGjG,+EAA+E;AAE/E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,OAAO;IACP,WAAW;IACX,QAAQ;IACR,KAAK;IACL,QAAQ;IACR,MAAM;IACN,UAAU;IACV,QAAQ;
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAA2B,UAAU,EAAE,CAAC;AAUlE,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAC9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAGjG,+EAA+E;AAE/E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ;IACR,OAAO;IACP,WAAW;IACX,QAAQ;IACR,KAAK;IACL,QAAQ;IACR,MAAM;IACN,UAAU;IACV,QAAQ;IACR,KAAK;CACG,CAAC;AAUX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAA8B,EAC9B,YAAiC;IAEjC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,WAAW,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ,CAAC;QACd,KAAK,MAAM,CAAC;QACZ,KAAK,KAAK;YACR,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,2EAA2E;YAC3E,gEAAgE;YAChE,OAAO,YAAY,EAAE,UAAU,KAAK,IAAI,CAAC;QAC3C;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}
|
package/openclaw.plugin.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"id": "claw-orchestrator",
|
|
3
3
|
"name": "Claw Orchestrator",
|
|
4
|
-
"description": "Run Claude Code, Codex, Antigravity, Grok Build, OpenCode and custom coding CLIs as one unified runtime. Persistent sessions, multi-engine orchestration, multi-agent council, worktree isolation, multi-model proxy, structured output, plan mode workflows.",
|
|
4
|
+
"description": "Run Claude Code, Codex, Antigravity, Grok Build, OpenCode, any ACP agent and custom coding CLIs as one unified runtime. Persistent sessions, multi-engine orchestration, multi-agent council, worktree isolation, multi-model proxy, structured output, plan mode workflows.",
|
|
5
5
|
"enabledByDefault": false,
|
|
6
6
|
"configSchema": {
|
|
7
7
|
"type": "object",
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@enderfga/claw-orchestrator",
|
|
3
|
-
"version": "7.
|
|
4
|
-
"description": "Claw Orchestrator — run Claude Code, Codex, Antigravity, Grok Build, OpenCode and custom coding CLIs as one unified runtime. Drop into Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose or any Model Context Protocol (MCP) host, install as an OpenClaw plugin, or run standalone. Persistent sessions, multi-agent council, ultraplan, ultrareview, autoloop, tool orchestration.",
|
|
3
|
+
"version": "7.14.0",
|
|
4
|
+
"description": "Claw Orchestrator — run Claude Code, Codex, Antigravity, Grok Build, OpenCode, any ACP agent and custom coding CLIs as one unified runtime. Drop into Hermes Agent, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf, Goose or any Model Context Protocol (MCP) host, install as an OpenClaw plugin, or run standalone. Persistent sessions, multi-agent council, ultraplan, ultrareview, autoloop, tool orchestration.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/src/index.js",
|
|
7
7
|
"types": "./dist/src/index.d.ts",
|
package/skills/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: claw-orchestrator
|
|
3
|
-
description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "auto research", "switch model", "hand off a session", "session handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent coding", "coding session", "session inbox", "grok session", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "verify a coding run", "acceptance contract", "evidence bundle", "did the agent's tests actually pass", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify", "clawo solve", "clawo fanout", "fix and verify", "solve from the terminal", "codex goal", "/goal", "clawo goal", "long-horizon goal", "unattended codex run", "goal node", "run codex in a sandbox", "launcher".
|
|
3
|
+
description: Manage persistent coding sessions across Claude Code, Codex, Antigravity (agy), Grok Build, and OpenCode engines. Use when orchestrating multi-engine coding agents, starting/sending/stopping sessions, running multi-agent council collaborations, cross-session messaging, ultraplan deep planning, ultrareview parallel code review, autoloop autonomous workspace iteration, ultraapp building deployable web apps from a structured Q&A interview, switching models/tools at runtime, exposing the orchestrator's 78 tools as an MCP server to Hermes Agent / Claude Desktop / Cursor / Cline / Continue / Zed / Windsurf / Goose, or running as an Agent Client Protocol (ACP) agent that Zed / JetBrains / Neovim / Emacs / VS Code / dsh can drive directly. Triggers on "start a session", "send to session", "run council", "ultraplan", "ultrareview", "autoloop", "ultraapp", "Forge tab", "build a web app", "one-click app", "AppSpec", "autonomous iteration", "iterate until goal", "auto research", "switch model", "hand off a session", "session handoff", "switch engine", "continue on codex", "continue on claude", "move this session to another engine", "multi-agent coding", "coding session", "session inbox", "grok session", "grok build", "opencode", "mcp server", "clawo-mcp", "hermes mcp", "model context protocol", "ultracode", "dynamic workflow", "fanout", "fan-out", "best-of-N", "steer turn", "interrupt turn", "fork thread", "rollback turns", "acp", "agent client protocol", "clawo acp", "zed agent", "jetbrains agent", "external agent", "dsh subagent", "deepseek harness", "acp engine", "acp agent", "kimi code", "kimi acp", "dsh acp", "any acp agent", "clawo runs", "run ledger", "session cost", "coding-agent token usage", "spend cap", "budget limit", "maxBudgetUsd", "durable workflow", "resume a run", "verify a coding run", "acceptance contract", "evidence bundle", "did the agent's tests actually pass", "protected tests", "agent edited the tests", "human gate", "repair loop", "clawo workflow", "clawo verify", "clawo solve", "clawo fanout", "fix and verify", "solve from the terminal", "codex goal", "/goal", "clawo goal", "long-horizon goal", "unattended codex run", "goal node", "run codex in a sandbox", "launcher".
|
|
4
4
|
metadata:
|
|
5
5
|
{
|
|
6
6
|
'openclaw':
|
package/skills/references/acp.md
CHANGED
|
@@ -8,6 +8,10 @@ spawns an arbitrary command as a subagent.
|
|
|
8
8
|
The model selector spans several engines, and session modes select the
|
|
9
9
|
orchestration shape: a single agent, a council, a planning pass, or a review.
|
|
10
10
|
|
|
11
|
+
The other direction, the orchestrator as an ACP **client** driving an agent such
|
|
12
|
+
as `kimi acp` or `dsh --profile acp`, is the `acp` engine: see
|
|
13
|
+
[multi-engine.md](./multi-engine.md#acp-agents-engine-acp).
|
|
14
|
+
|
|
11
15
|
```bash
|
|
12
16
|
clawo acp # or the dedicated binary:
|
|
13
17
|
clawo-acp
|
|
@@ -2,12 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
This document tracks which Claude Code CLI version Claw Orchestrator is currently synced to, and which features have been integrated. Recent rows also record the other engines' versions checked in the same sync.
|
|
4
4
|
|
|
5
|
-
## Currently tracked: **Claude Code CLI 2.1.
|
|
5
|
+
## Currently tracked: **Claude Code CLI 2.1.310** (as of 2026-10-25, plugin v7.14.0)
|
|
6
6
|
|
|
7
7
|
## Sync history
|
|
8
8
|
|
|
9
9
|
| Plugin Version | Claude CLI Version | Date | Notable integrations |
|
|
10
10
|
| ------------------- | ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| v7.14.0 | 2.1.310 | 2026-10-25 | CC 2.1.307→2.1.310, agy 1.4.4→1.4.6, grok 1.0.67→1.0.70, OpenCode 1.19.3→1.19.4; Codex 0.164.0 unchanged. No flag the wrappers pass changed; one live turn per engine ok. Integrated: the `acp` engine (an ACP client over `@agentclientprotocol/sdk` 1.3.0), run against Kimi Code 2.3.1 (`kimi acp`, model from `KIMI_MODEL_*`), dsh 0.2.1-rc.2 (`dsh --profile acp`, `--patch` honoured) and OpenCode 1.19.4 (`opencode acp`, recall across a resumed session). Kimi Code and dsh report no usage over ACP. |
|
|
11
12
|
| v7.13.0 | 2.1.307 | 2026-10-24 | Codex 0.163.0→0.164.0; the other engines as tracked in v7.12.1. Integrated: Codex 0.164 app-server goal RPCs (`thread/goal/set` / `get` / `clear`, six goal states, `tokenBudget`, `thread/goal/updated`), structured `error` notifications (`codexErrorInfo`, `willRetry`), `turn/steer` during goal turns, and `approvalPolicy` on `thread/start` / `thread/resume`; the `goal` workflow node is built on them. Measured: a goal objective is capped at 4,000 characters, and a thread can be resumed only after its first turn. |
|
|
12
13
|
| v7.12.1 | 2.1.307 | 2026-10-22 | CC 2.1.302→2.1.307, agy 1.4.0→1.4.4, grok 1.0.62→1.0.67; Codex 0.163.0 and OpenCode 1.19.3 unchanged. No flag the wrappers pass changed. grok 1.0.67 makes `grok-4.7` its default and only model: registered (same prices and 500K window as `grok-4.6`), the `grok` alias moved to it, and a session with no `model` is labelled with the model grok reports. grok read-only re-measured on 1.0.67 (direct and shell writes blocked; the subagent probe hit the free-tier limit). OpenCode 2 still beta-only, still refused. |
|
|
13
14
|
| v7.12.0 | 2.1.302 | 2026-10-17 | CC 2.1.296→2.1.302, Codex 0.162.1→0.163.0, agy 1.3.2→1.4.0, grok 1.0.50→1.0.62, OpenCode 1.19.0→1.19.3. No flag the wrappers pass changed. grok read-only re-measured on 1.0.62 (direct, shell and subagent writes blocked; the failed-sandbox warning unchanged). OpenCode 2 still beta-only, still refused. Codex 0.163.0 turns Daybreak (security programme, not a model) on for eligible accounts; billing follows the model codex reports. |
|
package/skills/references/cli.md
CHANGED
|
@@ -72,35 +72,36 @@ Run as an Agent Client Protocol agent over stdio (same as the `clawo-acp` binary
|
|
|
72
72
|
clawo session-start [name] [options]
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
-
| Flag | Description
|
|
76
|
-
| ------------------------------- |
|
|
77
|
-
| `-d, --cwd <dir>` | Working directory
|
|
78
|
-
| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, `codex-app`, `agy`, `grok`, `opencode`, or `custom`
|
|
79
|
-
| `-m, --model <model>` | Model name or alias
|
|
80
|
-
| `--permission-mode <mode>` | `acceptEdits` (default), `plan`, `auto`, `bypassPermissions`, `manual`, `dontAsk`
|
|
81
|
-
| `--effort <level>` | `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, `auto`
|
|
82
|
-
| `--allowed-tools <tools>` | Comma-separated tool whitelist
|
|
83
|
-
| `--disallowed-tools <tools>` | Comma-separated tools to deny
|
|
84
|
-
| `--max-turns <n>` | Max agent loop turns
|
|
85
|
-
| `--max-budget <usd>` | API cost ceiling
|
|
86
|
-
| `--system-prompt <text>` | Replace system prompt
|
|
87
|
-
| `--append-system-prompt <text>` | Append to system prompt
|
|
88
|
-
| `--agents <json>` | Custom sub-agents JSON
|
|
89
|
-
| `--agent <name>` | Default agent
|
|
90
|
-
| `--bare` | No CLAUDE.md, no git context
|
|
91
|
-
| `-w, --worktree [name]` | Git worktree
|
|
92
|
-
| `--fallback-model <model>` | Fallback model
|
|
93
|
-
| `--json-schema <schema>` | JSON Schema for structured output
|
|
94
|
-
| `--mcp-config <paths>` | MCP config files (comma-separated)
|
|
95
|
-
| `--settings <pathOrJson>` | Settings.json path or inline JSON
|
|
96
|
-
| `--skip-persistence` | Do not save the session — neither the engine's transcript nor the resume registry
|
|
97
|
-
| `--betas <headers>` | Beta headers (comma-separated)
|
|
98
|
-
| `--enable-agent-teams` | Enable agent teams
|
|
99
|
-
| `--enable-auto-mode` | Enable auto permission mode
|
|
100
|
-
| `--resume-session-id <id>` | Resume an existing session by ID
|
|
101
|
-
| `--base-url <url>` | Custom API endpoint (for proxy)
|
|
102
|
-
| `--add-dir <dirs>` | Comma-separated additional working directories
|
|
103
|
-
| `--custom-engine <preset>` | With `-e custom`: the id of a bundled engine preset (see [`clawo engines`](#clawo-engines))
|
|
75
|
+
| Flag | Description |
|
|
76
|
+
| ------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
77
|
+
| `-d, --cwd <dir>` | Working directory |
|
|
78
|
+
| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, `codex-app`, `agy`, `grok`, `opencode`, `acp`, or `custom` |
|
|
79
|
+
| `-m, --model <model>` | Model name or alias |
|
|
80
|
+
| `--permission-mode <mode>` | `acceptEdits` (default), `plan`, `auto`, `bypassPermissions`, `manual`, `dontAsk` |
|
|
81
|
+
| `--effort <level>` | `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, `auto` |
|
|
82
|
+
| `--allowed-tools <tools>` | Comma-separated tool whitelist |
|
|
83
|
+
| `--disallowed-tools <tools>` | Comma-separated tools to deny |
|
|
84
|
+
| `--max-turns <n>` | Max agent loop turns |
|
|
85
|
+
| `--max-budget <usd>` | API cost ceiling |
|
|
86
|
+
| `--system-prompt <text>` | Replace system prompt |
|
|
87
|
+
| `--append-system-prompt <text>` | Append to system prompt |
|
|
88
|
+
| `--agents <json>` | Custom sub-agents JSON |
|
|
89
|
+
| `--agent <name>` | Default agent |
|
|
90
|
+
| `--bare` | No CLAUDE.md, no git context |
|
|
91
|
+
| `-w, --worktree [name]` | Git worktree |
|
|
92
|
+
| `--fallback-model <model>` | Fallback model |
|
|
93
|
+
| `--json-schema <schema>` | JSON Schema for structured output |
|
|
94
|
+
| `--mcp-config <paths>` | MCP config files (comma-separated) |
|
|
95
|
+
| `--settings <pathOrJson>` | Settings.json path or inline JSON |
|
|
96
|
+
| `--skip-persistence` | Do not save the session — neither the engine's transcript nor the resume registry |
|
|
97
|
+
| `--betas <headers>` | Beta headers (comma-separated) |
|
|
98
|
+
| `--enable-agent-teams` | Enable agent teams |
|
|
99
|
+
| `--enable-auto-mode` | Enable auto permission mode |
|
|
100
|
+
| `--resume-session-id <id>` | Resume an existing session by ID |
|
|
101
|
+
| `--base-url <url>` | Custom API endpoint (for proxy) |
|
|
102
|
+
| `--add-dir <dirs>` | Comma-separated additional working directories |
|
|
103
|
+
| `--custom-engine <preset>` | With `-e custom`: the id of a bundled engine preset (see [`clawo engines`](#clawo-engines)) |
|
|
104
|
+
| `--acp-agent <preset>` | With `-e acp`: the id of a bundled ACP agent preset, e.g. `kimi-code`, `dsh` |
|
|
104
105
|
|
|
105
106
|
The remaining `session_start` options (hook events, permission-prompt tool, debug output, `fromPr`, MCP channels, prompt-cache settings and others) are tool parameters only and have no CLI flag. See [Tools Reference](./tools.md#session_start).
|
|
106
107
|
|
|
@@ -108,14 +109,19 @@ The remaining `session_start` options (hook events, permission-prompt tool, debu
|
|
|
108
109
|
|
|
109
110
|
```bash
|
|
110
111
|
clawo session-send <name> <message> [options]
|
|
112
|
+
clawo session-send <name> --message-file <file> [options]
|
|
111
113
|
```
|
|
112
114
|
|
|
113
|
-
| Flag
|
|
114
|
-
|
|
|
115
|
-
| `--
|
|
116
|
-
| `--
|
|
117
|
-
|
|
|
118
|
-
| `-
|
|
115
|
+
| Flag | Description |
|
|
116
|
+
| ----------------------- | ---------------------------------------------------------------------------- |
|
|
117
|
+
| `--message-file <file>` | Read the message from a file (long text, or text starting with `-`) |
|
|
118
|
+
| `--effort <level>` | Override effort for this message |
|
|
119
|
+
| `--plan` | Enable plan mode |
|
|
120
|
+
| `-s, --stream` | Collect streaming chunks |
|
|
121
|
+
| `-t, --timeout <ms>` | Timeout (default 300000) |
|
|
122
|
+
| `--json` | Print the whole result (`ok`, `output`, `sessionId`, `error`, …) as one line |
|
|
123
|
+
|
|
124
|
+
Every command that fails prints `Failed: …` and exits 1.
|
|
119
125
|
|
|
120
126
|
### session-stop
|
|
121
127
|
|
|
@@ -132,9 +138,11 @@ clawo session-list
|
|
|
132
138
|
### session-status
|
|
133
139
|
|
|
134
140
|
```bash
|
|
135
|
-
clawo session-status <name>
|
|
141
|
+
clawo session-status <name> [--json]
|
|
136
142
|
```
|
|
137
143
|
|
|
144
|
+
`--json` prints the whole status (`stats` with turns, tool calls, tokens, cost and the engine's resume id) as one line.
|
|
145
|
+
|
|
138
146
|
### session-grep
|
|
139
147
|
|
|
140
148
|
```bash
|
|
@@ -300,7 +308,7 @@ files included).
|
|
|
300
308
|
|
|
301
309
|
## `clawo engines`
|
|
302
310
|
|
|
303
|
-
Lists the community engine presets bundled with the installed package, with each
|
|
311
|
+
Lists the community engine presets bundled with the installed package (custom engines and ACP agents), with each
|
|
304
312
|
one's provenance — who attested it, against which engine version, on what date.
|
|
305
313
|
Read locally rather than over HTTP, since it is a property of the package and has
|
|
306
314
|
to work with no server running.
|
|
@@ -309,9 +317,10 @@ to work with no server running.
|
|
|
309
317
|
clawo engines
|
|
310
318
|
clawo engines --json
|
|
311
319
|
clawo session-start my-session -e custom --custom-engine <id>
|
|
320
|
+
clawo session-start my-session -e acp --acp-agent <id> # an ACP agent preset
|
|
312
321
|
```
|
|
313
322
|
|
|
314
|
-
A preset id is the only form of custom engine the CLI can pass: it reaches the
|
|
323
|
+
A preset id is the only form of custom engine or ACP agent the CLI can pass: it reaches the
|
|
315
324
|
session through the HTTP surface, which refuses inline configs because those name
|
|
316
325
|
a binary and its arguments. See [multi-engine.md](./multi-engine.md) for the tiers
|
|
317
326
|
and what a community preset does and does not claim.
|
|
@@ -316,6 +316,26 @@ await manager.startSession({
|
|
|
316
316
|
});
|
|
317
317
|
```
|
|
318
318
|
|
|
319
|
+
### ACP agents (`engine: 'acp'`)
|
|
320
|
+
|
|
321
|
+
Drives any agent that serves the [Agent Client Protocol](https://agentclientprotocol.com) on stdio, with no per-agent code. Run through it so far: Kimi Code 2.3.1 (`kimi acp`), DeepSeek's dsh 0.2.1-rc.2 (`dsh --profile acp`) and OpenCode 1.19.4 (`opencode acp`). This is the client side of the protocol; [acp.md](./acp.md) is the other side, where the orchestrator is the agent.
|
|
322
|
+
|
|
323
|
+
- `acpAgent` names the agent: a bundled preset id (`kimi-code`, `dsh`; `clawo engines` lists them), or, from a local caller only, an inline `{ name, command, commandEnv?, args?, env?, contextWindow?, pricing? }`. Over HTTP, which includes the `clawo` CLI, only a preset id is accepted, as for `customEngine`.
|
|
324
|
+
- One agent process per session; each send is one `session/prompt` on one ACP session, so the conversation carries over between sends. `initialize` advertises no `fs` or `terminal` capability: the agent reads, writes and runs commands with its own tools.
|
|
325
|
+
- A turn succeeds when the agent ends it with `stopReason: "end_turn"`; any other stop reason (`refusal`, `max_tokens`, `cancelled`, …) fails it. A turn that runs past its timeout is cancelled with `session/cancel`. An agent that exits mid-turn fails the turn and the session.
|
|
326
|
+
- `session/request_permission` is answered at once from `permissionMode`: `bypassPermissions`, `acceptEdits`, `auto` and `dontAsk` pick an allow option, the others a reject option. Nothing waits on a person.
|
|
327
|
+
- Resume: the agent's session id is the resume id (`stats.acpSessionId`). A resumed session reattaches it with `session/resume`, or `session/load` when that is all the agent offers; an agent with neither fails the start rather than opening a new conversation.
|
|
328
|
+
- Usage and cost are whatever the agent reports (`PromptResponse.usage`, `usage_update`). With `pricing` set and no reported cost, the cost is estimated from the reported tokens. Kimi Code 2.3.1 and dsh 0.2.1-rc.2 report neither, so their sessions show 0 tokens and $0. OpenCode reports tokens.
|
|
329
|
+
- The model and credentials are the agent's own configuration, set in its environment:
|
|
330
|
+
- Kimi Code: `KIMI_MODEL_NAME`, `KIMI_MODEL_API_KEY`, `KIMI_MODEL_BASE_URL`, `KIMI_MODEL_MAX_CONTEXT_SIZE`, `KIMI_MODEL_CAPABILITIES`, or a `kimi` login. `KIMI_BIN` overrides the command.
|
|
331
|
+
- dsh: `DEEPSEEK_API_KEY` (and `DEEPSEEK_BASE_URL`); its profile chooses the model. `DSH_BIN` overrides the command.
|
|
332
|
+
- `launcher` applies as for every engine.
|
|
333
|
+
|
|
334
|
+
```bash
|
|
335
|
+
clawo session-start kimi -e acp --acp-agent kimi-code --permission-mode bypassPermissions -d ./project
|
|
336
|
+
clawo session-send kimi "Fix the failing test in tests/test_io.py"
|
|
337
|
+
```
|
|
338
|
+
|
|
319
339
|
### Community engine presets
|
|
320
340
|
|
|
321
341
|
`customEngine` accepts either an inline `CustomEngineConfig` or the id of a preset
|
|
@@ -8,57 +8,58 @@ All 78 tools are registered as OpenClaw plugin tools and exposed over MCP by `cl
|
|
|
8
8
|
|
|
9
9
|
Start a persistent coding session with full CLI flag support.
|
|
10
10
|
|
|
11
|
-
| Parameter | Type
|
|
12
|
-
| ------------------------------------ |
|
|
13
|
-
| `name` | string
|
|
14
|
-
| `cwd` | string
|
|
15
|
-
| `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'agy'` \| `'grok'` \| `'opencode'` \| `'custom'` | Engine to use (default: `claude`). `agy` wraps Google Antigravity CLI. `grok` wraps xAI Grok Build and reports its own per-turn cost. `opencode` wraps sst/opencode (pass model as `provider/model`). Use `custom` with `customEngine` for any CLI. (`'gemini'` and `'cursor'` are still accepted for existing callers but are legacy — not version-tracked; use `agy` for Google and `grok` in place of Cursor.)
|
|
16
|
-
| `model` | string
|
|
17
|
-
| `permissionMode` | string
|
|
18
|
-
| `sandboxMode` | `'read-only'` \| `'workspace-write'` \| `'danger-full-access'`
|
|
19
|
-
| `allowedTools` | string[]
|
|
20
|
-
| `disallowedTools` | string[]
|
|
21
|
-
| `maxTurns` | number
|
|
22
|
-
| `maxBudgetUsd` | number
|
|
23
|
-
| `autoCompactPercent` | number
|
|
24
|
-
| `systemPrompt` | string
|
|
25
|
-
| `appendSystemPrompt` | string
|
|
26
|
-
| `agents` | object
|
|
27
|
-
| `agent` | string
|
|
28
|
-
| `bare` | boolean
|
|
29
|
-
| `worktree` | string \| boolean
|
|
30
|
-
| `fallbackModel` | string \| string[]
|
|
31
|
-
| `resumeSessionId` | string
|
|
32
|
-
| `jsonSchema` | string
|
|
33
|
-
| `mcpConfig` | string \| string[]
|
|
34
|
-
| `settings` | string
|
|
35
|
-
| `ultracode` | boolean
|
|
36
|
-
| `noSessionPersistence` | boolean
|
|
37
|
-
| `ignoreUserConfig` | boolean
|
|
38
|
-
| `codexProfile` | string
|
|
39
|
-
| `restricted` | boolean
|
|
40
|
-
| `betas` | string \| string[]
|
|
41
|
-
| `enableAgentTeams` | boolean
|
|
42
|
-
| `enableAutoMode` | boolean
|
|
43
|
-
| `customEngine` | object
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
49
|
-
| `
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
11
|
+
| Parameter | Type | Description |
|
|
12
|
+
| ------------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
13
|
+
| `name` | string | Session name (auto-generated if omitted) |
|
|
14
|
+
| `cwd` | string | Working directory |
|
|
15
|
+
| `engine` | `'claude'` \| `'codex'` \| `'codex-app'` \| `'agy'` \| `'grok'` \| `'opencode'` \| `'acp'` \| `'custom'` | Engine to use (default: `claude`). `agy` wraps Google Antigravity CLI. `grok` wraps xAI Grok Build and reports its own per-turn cost. `opencode` wraps sst/opencode (pass model as `provider/model`). `acp` drives any Agent Client Protocol agent named by `acpAgent`. Use `custom` with `customEngine` for any CLI. (`'gemini'` and `'cursor'` are still accepted for existing callers but are legacy — not version-tracked; use `agy` for Google and `grok` in place of Cursor.) |
|
|
16
|
+
| `model` | string | Model alias or full name |
|
|
17
|
+
| `permissionMode` | string | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
|
|
18
|
+
| `sandboxMode` | `'read-only'` \| `'workspace-write'` \| `'danger-full-access'` | Sandbox policy. Codex supports all values. `read-only` is enforced on every other built-in engine too: Claude → plan mode; Antigravity → its plan mode; OpenCode → a generated `clawo-readonly` agent denying `edit`/`bash`. Grok → its OS-enforced `--sandbox read-only` profile (refused for a project under the temp directory, on platforms without Seatbelt or Landlock, and when grok cannot apply it). A `custom` engine must map it via `permissionModes`, or the session refuses to start. Persisted across session resume. |
|
|
19
|
+
| `allowedTools` | string[] | Tools to auto-approve |
|
|
20
|
+
| `disallowedTools` | string[] | Tools to deny |
|
|
21
|
+
| `maxTurns` | number | Max agent loop turns |
|
|
22
|
+
| `maxBudgetUsd` | number | Max API spend (USD). Enforced by the runtime on every engine: once the session's cumulative cost reaches the cap, further sends are refused before the engine is spawned. See [observability.md](observability.md) for the accuracy caveat on engines that estimate token counts. |
|
|
23
|
+
| `autoCompactPercent` | number | Compact the conversation before a send once `contextPercent` reaches this value (1–99). Off by default. For long-lived sessions, where cost grows with context size; survives a server restart. A failed compaction does not block the send. |
|
|
24
|
+
| `systemPrompt` | string | Replace system prompt |
|
|
25
|
+
| `appendSystemPrompt` | string | Append custom instructions to the system prompt. Claude Code and Grok take it natively; Codex, Antigravity and OpenCode have no such flag and receive it at the top of the first message of a conversation |
|
|
26
|
+
| `agents` | object | Custom sub-agents JSON |
|
|
27
|
+
| `agent` | string | Default agent to use |
|
|
28
|
+
| `bare` | boolean | Skip hooks, LSP, auto-memory, CLAUDE.md |
|
|
29
|
+
| `worktree` | string \| boolean | Run in git worktree |
|
|
30
|
+
| `fallbackModel` | string \| string[] | Fallback model(s) when the primary is overloaded; an array is tried in order |
|
|
31
|
+
| `resumeSessionId` | string | Resume existing session by ID |
|
|
32
|
+
| `jsonSchema` | string | JSON Schema for structured output. Claude: `--json-schema` (inline). Codex: `--output-schema` (written to a temp file, requires Codex 0.132+). Other engines ignore it. |
|
|
33
|
+
| `mcpConfig` | string \| string[] | MCP server config file(s) |
|
|
34
|
+
| `settings` | string | Settings.json path or inline JSON |
|
|
35
|
+
| `ultracode` | boolean | Claude only. Enable "ultracode" / dynamic workflows — Claude plans a JS orchestration script per substantive task and fans out to subagents. Injected as the `ultracode:true` settings key (merged into `settings`). The workflow runs in the background: `session_send` returns at launch, and the completion turn is not returned by a later send (see sessions.md). |
|
|
36
|
+
| `noSessionPersistence` | boolean | Do not save session to disk — both the engine's own transcript and this orchestrator's resume registry, so a later start under the same name does not reattach |
|
|
37
|
+
| `ignoreUserConfig` | boolean | Codex only. Run without loading `$CODEX_HOME/config.toml`, so an orchestrated run is decided by what the caller passed rather than by the machine's own Codex config — notably a `model = …` line in that file, which otherwise picks the model while the ledger records this engine's default. Auth still resolves from `CODEX_HOME`. |
|
|
38
|
+
| `codexProfile` | string | Codex only. Named profile from `~/.codex/config.toml`, passed as `codex exec --profile` |
|
|
39
|
+
| `restricted` | boolean | Claude Code only. Restricted mode (`--restricted`): the CLI removes the built-in tools that run commands or code — Bash, PowerShell, the REPL — plus `WebFetch` unless `tools` names them, and ignores user, project and local settings files. Separate from `sandboxMode: 'read-only'`: that maps to plan mode, which holds on its own, while this makes the shell absent rather than refused. It also drops the caller's CLAUDE.md and hooks, so it is never switched on implicitly. |
|
|
40
|
+
| `betas` | string \| string[] | Custom beta headers |
|
|
41
|
+
| `enableAgentTeams` | boolean | Enable experimental agent teams |
|
|
42
|
+
| `enableAutoMode` | boolean | Enable auto permission mode |
|
|
43
|
+
| `customEngine` | object | Custom engine config (required when `engine='custom'`). See [Multi-Engine: Custom Engine](./multi-engine.md#custom-engine-engine-custom). |
|
|
44
|
+
| `acpAgent` | string \| object | The ACP agent (required when `engine='acp'`): a bundled preset id (`kimi-code`, `dsh`), or, from a local caller only, `{ name, command, commandEnv?, args?, env? }`. See [Multi-Engine: ACP agents](./multi-engine.md#acp-agents-engine-acp). |
|
|
45
|
+
| `crossSessionInbound` | string | `accept` / `hold` / `refuse` — policy for peer messages from other Claude Code sessions on this machine (Claude engine). Delivered as a settings key; there is no CLI flag. Without it the CLI holds messages whose two sides run different permission modes, which is the usual orchestrated-session-to-human-terminal case |
|
|
46
|
+
| `includeHookEvents` | boolean | Stream hook lifecycle events (PreToolUse/PostToolUse) as `system` events |
|
|
47
|
+
| `forwardSubagentText` | boolean | Forward subagent text and thinking into the output stream (Claude engine, CLI 2.1.211+). Without it the parent stream stays quiet while a subagent works |
|
|
48
|
+
| `chrome` | boolean | Let the session use the user's Chrome through the Claude in Chrome extension, acting with that browser's sign-ins (Claude engine, `--chrome`). Off by default. Needs Chrome running with the extension and a claude.ai login; survives a server restart |
|
|
49
|
+
| `permissionPromptTool` | string | MCP tool name to delegate permission prompts to (non-interactive use). When omitted, the session runs with `--permission-prompts none`: a prompt nobody could answer is denied rather than left waiting until the turn timeout. |
|
|
50
|
+
| `excludeDynamicSystemPromptSections` | boolean | Move cwd/env/git context from system prompt to user message for better prompt cache hits; auto-enabled with `bare: true` |
|
|
51
|
+
| `enablePromptCaching1H` | boolean | Enable 1-hour prompt cache TTL (vs default 5-min); auto-enabled with `bare: true` |
|
|
52
|
+
| `debug` | string \| string[] | Debug categories to enable (e.g. `"api,mcp"` or `["api", "mcp"]`) |
|
|
53
|
+
| `debugFile` | string | File path to write debug output to |
|
|
54
|
+
| `fromPr` | string | Resume a session linked to a GitHub PR number or URL |
|
|
55
|
+
| `channels` | string \| string[] | MCP channel subscription spec (research preview) |
|
|
56
|
+
| `dangerouslyLoadDevelopmentChannels` | string \| string[] | Development MCP channel subscriptions (research preview) |
|
|
57
|
+
| `forkSubagent` | boolean | Fork subagent for non-interactive sessions (sets `CLAUDE_CODE_FORK_SUBAGENT=1`) |
|
|
58
|
+
| `enableToolSearch` | boolean | Enable Vertex AI tool search (sets `ENABLE_TOOL_SEARCH=1`) |
|
|
59
|
+
| `otelLogUserPrompts` | boolean | OpenTelemetry: log user prompts (sets `OTEL_LOG_USER_PROMPTS=1`) |
|
|
60
|
+
| `otelLogRawApiBodies` | boolean | OpenTelemetry: log raw API request/response bodies (sets `OTEL_LOG_RAW_API_BODIES=1`); debug only |
|
|
61
|
+
| `bedrockServiceTier` | `'default'` \| `'flex'` \| `'priority'` | AWS Bedrock service tier (sets `ANTHROPIC_BEDROCK_SERVICE_TIER`); only effective when routing through Bedrock |
|
|
62
|
+
| `effort` | `'low'` \| `'medium'` \| `'high'` \| `'xhigh'` \| `'max'` \| `'ultra'` \| `'auto'` | Reasoning effort level. Engines do not share one ladder: Claude Code takes up to `max`, Codex adds `ultra`, Grok stops at `xhigh`, Antigravity at `high`, and OpenCode forwards the level to its provider unvalidated. A level above an engine's ceiling clamps rather than being dropped. `high` and above trigger the `ultrathink` prefix on Claude user messages. |
|
|
62
63
|
|
|
63
64
|
### `session_send`
|
|
64
65
|
|