feat: implement MCP proxy for OpenClaw tool access in contractor agent
Complete the MCP tool call chain: - contractor-agent bridge exposes /mcp/execute endpoint for tool callbacks - openclaw-mcp-server.mjs proxies OpenClaw tool defs to Claude as MCP tools - sdk-adapter passes --mcp-config on first turn with all OpenClaw tools - tool-test plugin registers contractor_echo in globalThis tool handler map - agent-config-writer auto-sets tools.profile=full so OpenClaw sends tool defs - Fix --mcp-config arg ordering: prompt must come before <configs...> flag Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -2,279 +2,52 @@
|
||||
|
||||
## Project Goal
|
||||
|
||||
Build an OpenClaw integration that turns contractor coding agents such as Claude Code into OpenClaw-managed agents.
|
||||
Build an OpenClaw plugin that turns Claude Code into an OpenClaw-managed contractor agent.
|
||||
|
||||
Phase 1 focuses on Claude Code only. Gemini support is deferred.
|
||||
Phase 1: Claude only. Gemini 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.
|
||||
OpenClaw manages agent identity, routing, workspace, and session ownership.
|
||||
Claude Code manages the live conversational and task context for its own session.
|
||||
The plugin bridges the two without duplicating context management.
|
||||
|
||||
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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
See ARCHITECTURE.md for component design.
|
||||
See IMPLEMENTATION.md for file structure and build order.
|
||||
See BRIDGE_MODEL_FINDINGS.md for probe test results that confirm the design.
|
||||
|
||||
## 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
|
||||
- Claude contractor agent provisioning via plugin-owned CLI
|
||||
- `contractor-claude-bridge` model: OpenAI-compatible sidecar that proxies OpenClaw turns into Claude Code sessions
|
||||
- Session map: persistent mapping of OpenClaw session keys to Claude session UUIDs
|
||||
- Input filter: strip OpenClaw system prompt, extract latest user message, inject one-time bootstrap
|
||||
- SSE streaming: bridge sidecar must stream Claude output back as SSE
|
||||
- Install script: writes provider config to `openclaw.json`, registers plugin
|
||||
|
||||
### Out of scope for now
|
||||
|
||||
- Gemini implementation
|
||||
- full OpenClaw skill auto-conversion
|
||||
- complete tool surface bridging
|
||||
- advanced recovery and replay semantics
|
||||
- Full OpenClaw tool bridging to Claude
|
||||
- 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?
|
||||
1. ~~What is the implementation seam for the bridge model?~~ **Resolved** — `openclaw.json` provider entry pointing to a local OpenAI-compatible sidecar. No plugin SDK model registration API. See BRIDGE_MODEL_FINDINGS.md.
|
||||
2. How should contractor metadata be persisted — agent runtime stanza, plugin config, or both?
|
||||
3. ~~What is the canonical identifier for Claude session continuation?~~ **Resolved** — UUID returned as `message.session_id` from the Claude Agent SDK. Resume via `options.resume`. See BRIDGE_MODEL_FINDINGS.md.
|
||||
4. Which minimal OpenClaw tools should be exposed first to Claude? (deferred to later)
|
||||
5. How should `/reset` and `/new` map to Claude-side session recreation?
|
||||
|
||||
## Immediate Next Steps
|
||||
## 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
|
||||
1. ~~Verify bridge model registration mechanism~~ Done
|
||||
2. ~~Verify Claude session continuation identifier~~ Done
|
||||
3. **Build bridge sidecar** with SSE streaming and Claude SDK dispatch
|
||||
4. Implement input filter and session map store
|
||||
5. Add bootstrap injection and recovery
|
||||
6. Implement CLI (`openclaw contractor-agents add`)
|
||||
7. Write install script
|
||||
|
||||
Reference in New Issue
Block a user