281 lines
8.9 KiB
Markdown
281 lines
8.9 KiB
Markdown
# ContractorAgent Plan
|
|
|
|
## Project Goal
|
|
|
|
Build an OpenClaw integration that turns contractor coding agents such as Claude Code into OpenClaw-managed agents.
|
|
|
|
Phase 1 focuses on Claude Code only. Gemini support is deferred.
|
|
|
|
## Product Direction
|
|
|
|
The goal is not merely to launch Claude Code from OpenClaw, but to make Claude Code behave like an OpenClaw-managed agent while preserving Claude Code's own model capability and execution workflow.
|
|
|
|
Desired properties:
|
|
|
|
- OpenClaw manages agent identity, routing, workspace, and session ownership
|
|
- Claude Code manages the live conversational and task context for its own session
|
|
- OpenClaw tools and skills are adapted into forms Claude Code can consume
|
|
- OpenClaw channels and sessions remain the outer control plane
|
|
|
|
## Core Design
|
|
|
|
### Session Proxy Runtime
|
|
|
|
Use a session proxy runtime rather than replaying full OpenClaw-managed context into Claude Code on every turn.
|
|
|
|
Important implementation note: in OpenClaw this should be delivered as a **custom model**.
|
|
|
|
Reason:
|
|
|
|
- OpenClaw expects each agent to have a primary model
|
|
- for this special contractor agent, the real primary intelligence is provided by Claude Code
|
|
- therefore the most natural integration seam is a custom model that accepts OpenClaw messages, routes them into the mapped Claude Code session, and then injects Claude's response back into OpenClaw session state
|
|
|
|
So although the architecture is conceptually a session proxy runtime, the concrete integration form inside OpenClaw should be a **bridge model** or **pseudo-model backend** for Claude-backed agents.
|
|
|
|
Core idea:
|
|
|
|
- map each OpenClaw session to a Claude Code session
|
|
- on each new user message, find the mapped Claude session
|
|
- resume or continue that Claude session
|
|
- forward only the newest actionable message plus minimal metadata
|
|
- avoid rebuilding full prompt history on every turn
|
|
- return the Claude response through the custom model seam so it becomes part of normal OpenClaw agent flow
|
|
|
|
This reduces:
|
|
|
|
- duplicated context management
|
|
- token waste
|
|
- divergence between OpenClaw-visible history and Claude's actual working memory
|
|
|
|
### Control Plane Split
|
|
|
|
OpenClaw remains source of truth for:
|
|
|
|
- agent registration
|
|
- routing and bindings
|
|
- workspace ownership
|
|
- permissions and approvals
|
|
- channel transport
|
|
- tool hosting
|
|
|
|
Claude Code remains source of truth for:
|
|
|
|
- live conversation state within a contractor session
|
|
- reasoning and coding flow
|
|
- internal execution trajectory
|
|
|
|
## Feasibility Notes from Docs
|
|
|
|
### OpenClaw ACP Agents
|
|
|
|
OpenClaw already supports Claude Code as an ACP harness runtime.
|
|
|
|
Relevant doc statements:
|
|
|
|
> "ACP sessions let OpenClaw run external coding harnesses (for example ... Claude Code ...) through an ACP backend plugin."
|
|
|
|
> "For Claude Code through ACP, the stack is:
|
|
> 1. OpenClaw ACP session control plane
|
|
> 2. bundled `acpx` runtime plugin
|
|
> 3. Claude ACP adapter
|
|
> 4. Claude-side runtime/session machinery"
|
|
|
|
This indicates Claude Code session hosting is already available as a foundation.
|
|
|
|
Source:
|
|
- https://docs.openclaw.ai/tools/acp-agents
|
|
|
|
### OpenClaw ACP Session Semantics
|
|
|
|
Relevant doc statements:
|
|
|
|
> "Follow-up messages in that conversation route to the same ACP session."
|
|
|
|
> "`/new` and `/reset` reset the same bound ACP session in place."
|
|
|
|
> "Use `resumeSessionId` to continue a previous ACP session instead of starting fresh."
|
|
|
|
These features support a persistent contractor-session bridge.
|
|
|
|
Source:
|
|
- https://docs.openclaw.ai/tools/acp-agents
|
|
|
|
### OpenClaw Plugin Extensibility
|
|
|
|
Relevant doc statements:
|
|
|
|
> "Plugins extend OpenClaw with new capabilities: channels, model providers, ... agent tools, or any combination."
|
|
|
|
> "Agent tools | `api.registerTool(...)`"
|
|
|
|
> "For provider plugins, tool plugins, hook plugins, and anything that is not a messaging channel."
|
|
|
|
These suggest a native OpenClaw plugin can host the contractor-agent bridge logic.
|
|
|
|
Sources:
|
|
- https://docs.openclaw.ai/plugins/building-plugins
|
|
- https://docs.openclaw.ai/plugins/sdk-entrypoints
|
|
|
|
### OpenClaw CLI Extension Surface
|
|
|
|
Plugins can register CLI commands, but current docs do not show support for patching an existing core command such as `openclaw agents add` with extra flags.
|
|
|
|
Relevant doc statements:
|
|
|
|
> "Common registration methods: ... `registerCommand` / `registerCli` | CLI commands"
|
|
|
|
> "For plugin-owned root CLI commands, prefer `api.registerCli(..., { descriptors: [...] })` ..."
|
|
|
|
Therefore the safer design is to add a plugin-owned command root rather than extending `openclaw agents add` directly.
|
|
|
|
Sources:
|
|
- https://docs.openclaw.ai/tools/plugin
|
|
- https://docs.openclaw.ai/plugins/sdk-entrypoints
|
|
|
|
### Claude Code Plugin Surface
|
|
|
|
Claude Code has a plugin model with skills, agents, hooks, MCP servers, and LSP servers.
|
|
|
|
Relevant doc statements:
|
|
|
|
> "A plugin is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, and LSP servers."
|
|
|
|
> "Plugins add skills to Claude Code ... Claude can invoke them automatically based on task context"
|
|
|
|
This supports the idea that OpenClaw skills and tooling may be adapted into Claude Code-friendly forms instead of being injected as raw prompt only.
|
|
|
|
Source:
|
|
- https://code.claude.com/docs/en/plugins-reference
|
|
|
|
## Bridge Model Direction
|
|
|
|
The contractor-agent implementation should expose one or more plugin-provided custom model ids for OpenClaw agents to use as their primary model.
|
|
|
|
For Claude phase 1, the working assumption is a model id in the shape of:
|
|
|
|
- `contractor-claude-bridge`
|
|
|
|
Behavior of this bridge model:
|
|
|
|
1. receive the agent turn from OpenClaw
|
|
2. identify the current OpenClaw session key and target contractor agent
|
|
3. resolve or create the mapped Claude Code session
|
|
4. filter OpenClaw-managed envelope/context so only the latest actionable message and minimal metadata are forwarded
|
|
5. send the turn to Claude Code through the chosen ACP/session continuation path
|
|
6. capture Claude's response
|
|
7. inject the response back into OpenClaw through the model response path and session file flow
|
|
|
|
This approach fits OpenClaw's requirement that every agent has a primary model while still allowing Claude Code to act as the true reasoning engine for contractor-backed agents.
|
|
|
|
## Initial CLI Plan
|
|
|
|
Introduce a plugin-owned command:
|
|
|
|
```bash
|
|
openclaw contractor-agents add --agent-id <agent-id> --workspace <workspace> --contractor <claude|gemini>
|
|
```
|
|
|
|
For phase 1, only `claude` is supported.
|
|
|
|
### Intended behavior
|
|
|
|
For `--contractor claude`, the command should:
|
|
|
|
1. call:
|
|
|
|
```bash
|
|
openclaw agents add <agent-id> --workspace <workspace> --model <bridge-model-id> --non-interactive
|
|
```
|
|
|
|
2. mark the created agent as a contractor-backed agent
|
|
3. persist contractor runtime metadata for that agent
|
|
4. prepare storage for OpenClaw-session to Claude-session mappings
|
|
|
|
## Proposed Agent Config Shape
|
|
|
|
Exact schema TBD, but directionally:
|
|
|
|
```json5
|
|
{
|
|
agents: {
|
|
list: [
|
|
{
|
|
id: "my-agent",
|
|
workspace: "/path/to/workspace",
|
|
model: "contractor-claude-bridge",
|
|
runtime: {
|
|
type: "contractor",
|
|
contractor: {
|
|
kind: "claude",
|
|
backend: "acp",
|
|
mode: "persistent"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Session Mapping Store
|
|
|
|
Keep dynamic mappings out of main config.
|
|
|
|
Suggested runtime state file location:
|
|
|
|
```text
|
|
<agent-workspace>/.openclaw/contractor-agent/session-map.json
|
|
```
|
|
|
|
Possible structure:
|
|
|
|
```json
|
|
{
|
|
"sessions": [
|
|
{
|
|
"openclawSessionKey": "agent:my-agent:main",
|
|
"claudeSessionId": "<resumeSessionId-or-runtime-id>",
|
|
"createdAt": "2026-04-10T00:00:00Z",
|
|
"lastActivityAt": "2026-04-10T00:00:00Z",
|
|
"state": "active"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Phase 1 Scope
|
|
|
|
### In scope
|
|
|
|
- Claude contractor agent creation flow
|
|
- plugin-owned CLI for contractor agent management
|
|
- bridge model placeholder for Claude-backed agents
|
|
- persistent mapping of OpenClaw sessions to Claude sessions
|
|
- initial Claude-only runtime design
|
|
- planning documents and repository structure
|
|
|
|
### Out of scope for now
|
|
|
|
- Gemini implementation
|
|
- full OpenClaw skill auto-conversion
|
|
- complete tool surface bridging
|
|
- advanced recovery and replay semantics
|
|
- UI polish and operational tooling
|
|
|
|
## Open Questions
|
|
|
|
1. What is the best implementation seam for the bridge model inside OpenClaw, provider plugin, tool plugin, or service-backed pseudo model?
|
|
2. How should contractor metadata be persisted, agent runtime stanza, plugin config, or both?
|
|
3. What is the canonical identifier for Claude session continuation, ACP session id, adapter resume id, or plugin-owned alias?
|
|
4. Which minimal OpenClaw tools should be exposed first to Claude?
|
|
5. How should reset/new map to Claude-side session recreation?
|
|
|
|
## Immediate Next Steps
|
|
|
|
1. Design the `openclaw contractor-agents add` CLI surface in detail
|
|
2. Define config schema for contractor-backed agents
|
|
3. Define session-map file schema and lifecycle
|
|
4. Determine how the bridge model id is registered by the plugin
|
|
5. Draft implementation skeleton for Claude-only support
|