docs: expand Claude contractor design
This commit is contained in:
307
docs/claude/CLI.md
Normal file
307
docs/claude/CLI.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# Contractor Agents CLI Design
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the plugin-owned CLI surface for managing contractor-backed OpenClaw agents.
|
||||
|
||||
Phase 1 supports Claude only. Gemini remains reserved in the command shape but is not implemented yet.
|
||||
|
||||
## Command root
|
||||
|
||||
```bash
|
||||
openclaw contractor-agents
|
||||
```
|
||||
|
||||
This should be implemented as a plugin-owned CLI root, not as a patch to `openclaw agents add`.
|
||||
|
||||
## Why a separate command root
|
||||
|
||||
Current OpenClaw plugin docs show support for plugin CLI registration, but do not document support for extending existing core commands with new flags.
|
||||
|
||||
Relevant doc statements:
|
||||
|
||||
> "Common registration methods: ... `registerCommand` / `registerCli` | CLI commands"
|
||||
|
||||
> "For plugin-owned root CLI commands, prefer `api.registerCli(..., { descriptors: [...] })` ..."
|
||||
|
||||
This suggests the supported extension seam is plugin-owned CLI trees.
|
||||
|
||||
Sources:
|
||||
- https://docs.openclaw.ai/tools/plugin
|
||||
- https://docs.openclaw.ai/plugins/sdk-entrypoints
|
||||
|
||||
## Phase 1 command
|
||||
|
||||
```bash
|
||||
openclaw contractor-agents add --agent-id <agent-id> --workspace <workspace> --contractor <claude|gemini>
|
||||
```
|
||||
|
||||
Phase 1 restrictions:
|
||||
|
||||
- `--contractor` must currently be `claude`
|
||||
- `gemini` is accepted only as a reserved future value if desired, but should currently fail with a clear not-yet-implemented message unless you intentionally decide to reject it at parsing time
|
||||
|
||||
## Arguments
|
||||
|
||||
### Required
|
||||
|
||||
- `--agent-id <agent-id>`
|
||||
- `--workspace <workspace>`
|
||||
- `--contractor <claude|gemini>`
|
||||
|
||||
### Optional, possible later
|
||||
|
||||
Not required for first implementation, but likely useful later:
|
||||
|
||||
- `--bridge-model <model-id>`
|
||||
- `--backend <acp-backend>`
|
||||
- `--mode <persistent|oneshot>`
|
||||
- `--json`
|
||||
- `--non-interactive`
|
||||
|
||||
For now, phase 1 can hardcode the bridge model and runtime defaults.
|
||||
|
||||
## Behavior of `add`
|
||||
|
||||
For:
|
||||
|
||||
```bash
|
||||
openclaw contractor-agents add --agent-id my-agent --workspace /path/to/ws --contractor claude
|
||||
```
|
||||
|
||||
The CLI should do the following.
|
||||
|
||||
### Step 1, validate inputs
|
||||
|
||||
- ensure `agent-id` is provided
|
||||
- ensure workspace exists or is creatable, based on your desired policy
|
||||
- ensure contractor kind is supported
|
||||
- ensure target agent does not already exist unless overwrite behavior is explicitly added later
|
||||
|
||||
### Step 2, create the base OpenClaw agent
|
||||
|
||||
Run the equivalent of:
|
||||
|
||||
```bash
|
||||
openclaw agents add <agent-id> --workspace <workspace> --model contractor-claude-bridge --non-interactive
|
||||
```
|
||||
|
||||
Important note:
|
||||
|
||||
Earlier review of `openclaw agents add` docs showed these supported options:
|
||||
|
||||
> `--workspace <dir>`
|
||||
> `--model <id>`
|
||||
> `--agent-dir <dir>`
|
||||
> `--bind <channel[:accountId]>`
|
||||
> `--non-interactive`
|
||||
> `--json`
|
||||
|
||||
Source:
|
||||
- https://docs.openclaw.ai/cli/agents
|
||||
|
||||
This means the contractor CLI can compose the existing agent creation flow rather than replacing it.
|
||||
|
||||
### Step 3, mark the agent as a contractor-backed agent
|
||||
|
||||
After agent creation, write contractor metadata so runtime selection and session bridging can identify this agent as contractor-managed.
|
||||
|
||||
Proposed config direction:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "my-agent",
|
||||
model: "contractor-claude-bridge",
|
||||
runtime: {
|
||||
type: "contractor",
|
||||
contractor: {
|
||||
kind: "claude",
|
||||
backend: "acp",
|
||||
mode: "persistent"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Exact schema is still TBD, but the CLI should be the mechanism that writes this state.
|
||||
|
||||
### Step 4, initialize contractor runtime state
|
||||
|
||||
Prepare runtime state for the agent, including a place to store session mappings.
|
||||
|
||||
Suggested path:
|
||||
|
||||
```text
|
||||
<workspace>/.openclaw/contractor-agent/
|
||||
```
|
||||
|
||||
Suggested initial files:
|
||||
|
||||
```text
|
||||
session-map.json
|
||||
runtime.json
|
||||
```
|
||||
|
||||
## Session mapping responsibility
|
||||
|
||||
The CLI does not create Claude sessions immediately unless you explicitly want eager setup.
|
||||
|
||||
Recommended phase 1 behavior:
|
||||
|
||||
- create agent metadata
|
||||
- create runtime state directory
|
||||
- initialize empty mapping file
|
||||
- defer real Claude session creation to first actual agent turn
|
||||
|
||||
This keeps `add` lightweight and avoids unused contractor sessions.
|
||||
|
||||
## Suggested future commands
|
||||
|
||||
These are not required immediately, but the command tree should reserve room for them.
|
||||
|
||||
### Status
|
||||
|
||||
```bash
|
||||
openclaw contractor-agents status --agent-id <agent-id>
|
||||
```
|
||||
|
||||
Show:
|
||||
- contractor kind
|
||||
- bridge model id
|
||||
- runtime backend
|
||||
- session mapping count
|
||||
- recent activity
|
||||
|
||||
### List sessions
|
||||
|
||||
```bash
|
||||
openclaw contractor-agents sessions --agent-id <agent-id>
|
||||
```
|
||||
|
||||
Show session mappings for the given contractor-backed agent.
|
||||
|
||||
### Reset mapping
|
||||
|
||||
```bash
|
||||
openclaw contractor-agents reset-session --agent-id <agent-id> --openclaw-session <session-key>
|
||||
```
|
||||
|
||||
Drop a specific OpenClaw-to-Claude mapping so the next message recreates the Claude session.
|
||||
|
||||
### Disable
|
||||
|
||||
```bash
|
||||
openclaw contractor-agents disable --agent-id <agent-id>
|
||||
```
|
||||
|
||||
Either:
|
||||
- remove contractor metadata but keep agent
|
||||
- or mark the contractor runtime disabled
|
||||
|
||||
Semantics TBD.
|
||||
|
||||
## JSON output
|
||||
|
||||
I recommend all subcommands eventually support `--json` so this can be scripted.
|
||||
|
||||
Example success response shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"agentId": "my-agent",
|
||||
"workspace": "/path/to/ws",
|
||||
"contractor": "claude",
|
||||
"model": "contractor-claude-bridge",
|
||||
"runtimeStateDir": "/path/to/ws/.openclaw/contractor-agent"
|
||||
}
|
||||
```
|
||||
|
||||
## Failure cases
|
||||
|
||||
The CLI should fail clearly for:
|
||||
|
||||
- unsupported contractor kind
|
||||
- agent already exists
|
||||
- workspace invalid or inaccessible
|
||||
- bridge model plugin not available
|
||||
- failure in underlying `openclaw agents add`
|
||||
- failure writing contractor metadata
|
||||
|
||||
If the agent is created successfully but metadata writing fails, the CLI should either:
|
||||
|
||||
- roll back the created agent if safe and simple
|
||||
- or return a partial-failure error with explicit cleanup instructions
|
||||
|
||||
Phase 1 recommendation: prefer explicit rollback if implementation is reliable.
|
||||
|
||||
## Interaction with the bridge model
|
||||
|
||||
The CLI should not directly run Claude Code or create a Claude contractor session by default.
|
||||
|
||||
Its main job is to provision an agent whose primary model is the contractor bridge model:
|
||||
|
||||
- `contractor-claude-bridge`
|
||||
|
||||
That model then handles runtime dispatch during actual conversation turns.
|
||||
|
||||
## Implementation notes
|
||||
|
||||
The plugin should register a root command owned by the plugin.
|
||||
|
||||
Relevant doc statements:
|
||||
|
||||
> "For plugin-owned root CLI commands, prefer `api.registerCli(..., { descriptors: [...] })` when you want the command to stay lazy-loaded without disappearing from the root CLI parse tree."
|
||||
|
||||
Source:
|
||||
- https://docs.openclaw.ai/plugins/sdk-entrypoints
|
||||
|
||||
So the intended shape is:
|
||||
|
||||
- plugin registers `contractor-agents`
|
||||
- plugin owns parsing and handling of its subcommands
|
||||
- plugin composes `openclaw agents add` behavior internally or via shared config/runtime helpers
|
||||
|
||||
## Open questions
|
||||
|
||||
1. Should the CLI shell out to `openclaw agents add` or use a lower-level config/runtime helper directly?
|
||||
2. Where should contractor metadata live, `agents.list[].runtime`, plugin config, or both?
|
||||
3. Should `gemini` be rejected now or accepted with a not implemented error?
|
||||
4. Should add create the workspace if it does not exist?
|
||||
5. Should agent creation be rolled back if contractor metadata writing fails?
|
||||
|
||||
## References
|
||||
|
||||
### Plugin CLI support
|
||||
|
||||
> "Common registration methods: ... `registerCommand` / `registerCli` | CLI commands"
|
||||
|
||||
Source:
|
||||
- https://docs.openclaw.ai/tools/plugin
|
||||
|
||||
### Plugin-owned CLI descriptors
|
||||
|
||||
> "For plugin-owned root CLI commands, prefer `api.registerCli(..., { descriptors: [...] })` ..."
|
||||
|
||||
Source:
|
||||
- https://docs.openclaw.ai/plugins/sdk-entrypoints
|
||||
|
||||
### Existing agent creation command
|
||||
|
||||
> `agents add [name]`
|
||||
|
||||
> `--workspace <dir>`
|
||||
> `--model <id>`
|
||||
> `--agent-dir <dir>`
|
||||
> `--bind <channel[:accountId]>`
|
||||
> `--non-interactive`
|
||||
> `--json`
|
||||
|
||||
Source:
|
||||
- https://docs.openclaw.ai/cli/agents
|
||||
Reference in New Issue
Block a user