Skip to content

docs: improve README with architecture, config, and troubleshooting #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Alex647648 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: improve README with architecture, config, and troubleshooting #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 44 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,63 @@
# OpenClaw Dimensional
# OpenClaw DimOS Bridge

In one terminal, run the following commands:
An [OpenClaw](https://openclaw.dev) plugin that bridges [DimOS](https://github.com/dimensionalOS/dimos) MCP tools into the OpenClaw agent system. It discovers tools from a running DimOS MCP server over TCP and registers them as native OpenClaw agent tools.

## Architecture

```bash
uv sync
```
OpenClaw Agent ──▶ roboclaw plugin (bridge) ──TCP/JSON-RPC──▶ DimOS MCP Server ──▶ Robot
```

1. On plugin registration, connects to the DimOS MCP server and discovers available tools
2. Converts each MCP tool's JSON Schema into TypeBox schemas for OpenClaw's type system
3. When the agent invokes a tool, forwards the call over TCP and returns the result

## Prerequisites

- [Node.js](https://nodejs.org/) >= 18
- [pnpm](https://pnpm.io/)
- [uv](https://github.com/astral-sh/uv) (for the Python DimOS server)
- Python >= 3.11

## Quick Start

**Terminal 1** — Start the DimOS MCP server:

```bash
uv sync
uv run dimos --viewer-backend rerun run unitree-go2-agentic-mcp
```

In another terminal, run the following commands:
**Terminal 2** — Start the OpenClaw gateway and run an agent:

```bash
pnpm install
```

```bash
pnpm openclaw config set plugins.entries.dimos.enabled true
pnpm openclaw gateway stop && pnpm openclaw gateway run --port 18789 --verbose gateway.mode=local
```

```bash
pnpm openclaw gateway stop && pnpm openclaw gateway run --port 18789 --verbose gateway.mode=local
pnpm openclaw agent --session-id dimos-test --message "move forward 10 meters"
```

## Configuration

Configure the plugin in your OpenClaw config:

| Option | Type | Default | Description |
|-----------|----------|---------------|------------------------------|
| `mcpHost` | `string` | `127.0.0.1` | DimOS MCP server hostname |
| `mcpPort` | `number` | `9990` | DimOS MCP server port |

Example:

```bash
pnpm openclaw agent --session-id dimos-test --message "move forward 10 meters"
pnpm openclaw config set plugins.entries.dimos.config.mcpHost "192.168.1.100"
pnpm openclaw config set plugins.entries.dimos.config.mcpPort 9991
```

## Troubleshooting

- **Plugin loads 0 tools**: Ensure the DimOS MCP server is running and reachable at the configured host:port before starting the OpenClaw gateway.
- **Connection refused**: Check that the port is correct and no firewall is blocking TCP connections to the DimOS server.
- **Timeout errors**: The default tool call timeout is 30 seconds. Long-running robot operations may need the DimOS server to respond within this window.