openclaw-claude-bridge solves a specific interoperability problem for AI developers who want to use Claude Code CLI through an OpenAI-compatible API interface provided by OpenClaw. The key technical insight is that this bridge acts purely as a translation layer — it never executes the tools itself but instead injects tool-call instructions and parses Claude’s XML responses to convert them into OpenAI’s expected format. This design enables seamless compatibility and extensibility, with zero changes needed in the bridge when new tools are added upstream in OpenClaw.
what openclaw-claude-bridge does and its architecture
At its core, openclaw-claude-bridge is an HTTP proxy server that converts between OpenClaw’s OpenAI-format API requests and the native protocol of Claude Code CLI. It listens on a local port and manages persistent CLI subprocess sessions for each agent and channel combination. This persistence is crucial because it allows stateful conversations and context to be maintained across multiple requests.
The bridge handles stdin/stdout management of the Claude CLI subprocess, feeding it commands and reading streaming responses. It uses server-sent events (SSE) to stream responses back to OpenClaw, facilitating real-time interaction.
A key architectural feature is how the bridge dynamically injects tool-calling instructions from OpenClaw’s tools array into Claude’s system prompt. Claude outputs tool-call blocks as XML, which the bridge parses and converts into OpenAI-style tool_calls. This translation layer means the bridge never executes tools itself; OpenClaw remains the source of truth for tool management and execution.
The bridge also supports extended “thinking” or reasoning by mapping OpenClaw’s reasoning_effort parameter to Claude CLI’s –effort flag, allowing fine-grained control over computational effort.
On top of the core proxy functionality, openclaw-claude-bridge includes a React-based dashboard served on port 3458. This dashboard provides real-time metrics such as per-agent cost tracking, context window usage, and session cleanup controls, which are valuable for monitoring and managing AI agent costs and performance in production.
The stack is primarily JavaScript, managing subprocesses and HTTP servers, with React for the dashboard UI. It targets macOS and Linux platforms with Node.js 18+ as the runtime.
technical strengths and tradeoffs
The standout feature is the bridge’s pure translation layer design. By never executing tools itself and relying entirely on OpenClaw for tool loops, the bridge achieves a clean separation of concerns. This means any new tools added in OpenClaw are immediately compatible with Claude via the bridge, without requiring bridge code changes.
The session management keyed by channel and agent name supports persistent, context-rich conversations essential for advanced AI workflows. Auto-resuming sessions across restarts using a state.json file improves robustness without manual intervention.
The XML to OpenAI tool_calls conversion is a clever workaround to bridge two different tooling ecosystems, enabling compatibility without modifying either end.
Tradeoffs include the added complexity of managing subprocesses and parsing streaming XML output, which can be fragile if Claude’s CLI output format changes. The bridge also depends on the Claude CLI being logged in and available locally, which may limit deployment scenarios.
The React dashboard is a nice touch but adds a UI layer that requires maintenance and may not be essential for all users. However, it greatly improves developer experience by exposing relevant runtime metrics.
Overall, the code structure appears clean and focused, with clear responsibility boundaries. The design choices prioritize compatibility and extensibility over reimplementing functionality.
quick start with openclaw-claude-bridge
To set up openclaw-claude-bridge with OpenClaw, add the following provider configuration to your ~/.openclaw/openclaw.json file:
{
"models": {
"providers": {
"claude-bridge": {
"baseUrl": "http://localhost:3456/v1",
"apiKey": "not-needed",
"api": "openai-completions",
"models": [
{
"id": "claude-opus-latest",
"name": "Claude Opus",
"contextWindow": 1000000,
"maxTokens": 128000,
"reasoning": true
},
{
"id": "claude-sonnet-latest",
"name": "Claude Sonnet",
"contextWindow": 1000000,
"maxTokens": 64000,
"reasoning": true
}
]
}
}
}
}
After adding this, assign the model to your agent in OpenClaw. The apiKey value can be any non-empty string, as the bridge does not enforce API key checks.
For service setup and auto-start on boot, the repository provides instructions for macOS using launchd. The main requirements are:
- Node.js version 18 or higher
- Claude Code CLI (latest) with a logged-in session (
claude auth login) - OpenClaw version 2026.1 or newer (gateway running on port 18789)
The supported platforms include macOS (both Apple Silicon and Intel) and Linux (x64 and ARM).
verdict
openclaw-claude-bridge is a practical solution for anyone looking to integrate Claude Code CLI into OpenClaw’s OpenAI-compatible ecosystem without rewriting tools or workflows. Its design as a pure translation and session management layer is elegant and enables rapid compatibility with new tools.
The bridge’s reliance on local CLI subprocesses and XML parsing introduces some fragility and operational constraints, so it may not suit cloud-native or large-scale distributed deployments without additional engineering.
That said, for developers working in environments where Claude CLI is accessible and OpenClaw is the main AI orchestration layer, this bridge offers a clean and maintainable way to support Claude agents with fine-grained session and cost management.
The built-in React dashboard is a nice bonus for monitoring but optional.
If your use case involves multiple AI providers or you want to unify tooling under OpenClaw’s API, openclaw-claude-bridge is worth evaluating. Just be prepared to manage local CLI dependencies and watch for changes in Claude’s output format that might require updates.
Overall, the repo is well-structured and focused, and it solves a real problem for multi-agent AI workflows with minimal overhead.
Related Articles
- how awesome-claude-skills turns claude into a real-world action agent — Awesome Claude Skills is a modular Python framework that empowers Claude to perform real-world actions by integrating wi
- OpenAI Codex CLI: local-first AI coding assistant with ChatGPT integration — OpenAI Codex CLI brings AI coding assistance local to your terminal, integrating with ChatGPT plans for powerful hybrid
→ GitHub Repo: shinglokto/openclaw-claude-bridge ⭐ 149 · JavaScript