openclaw-mcp-termux

An MCP (Model Context Protocol) server running natively on Android via Termux. Bridges Claude.ai or Claude Desktop to a locally-running OpenClaw gateway using 10 consolidated tools optimized for the God Orchestrator pattern.

---

Architecture

Sakaar (vision/intent)
  → Claude (compiler — frontier inference)
    → MCP Bridge (this server — 10 tools)
      → OpenClaw Gateway (127.0.0.1:18789)
        → Agents: Tani (main), Alan (coding), Rachel (rachel)

The MCP bridge is the transport layer between Claude's compiler and the OpenClaw execution agents. It provides three capabilities: dispatch (send tasks to agents), observe (monitor agent state), and control (intervene on running sessions).

Transport:

• stdio over SSH — Claude Desktop connects via ssh flip "node dist/index.js"
• Streamable HTTP — Claude.ai via Cloudflare Tunnel

Key design decisions:

• SSH-first CLI — all openclaw CLI calls route through ssh proot (~200ms) instead of the wrapper script (2-10s cold start)
• Filesystem-first reads — config/session/log reads hit files directly (~16ms) instead of shelling out to the CLI
• Env-based auth — gateway token from .env via dotenv, resolved relative to script location (handles SSH cwd != project dir)
• No Docker — runs natively in Termux Node.js, OpenClaw runs in proot-Ubuntu

---

10 Tools

Agent Orchestration

Tool	Description
agent_dispatch	Send tasks to agents. Three modes: async (fire-and-forget via webhook), sync (wait for reply), spawn (tracked sub-agent delegation with runId). Routes to Tani/Alan/Rachel.
agent_query	Multi-view observation. Views: health (gateway status), sessions (all agent sessions with JSONL metadata), actions (active processes + recent tool calls + log tail), logs (gateway/command/heartbeat/rclone scenarios), history (JSONL transcript read).
agent_control	Session management: abort, steer, compact, reset. Returns 404 for all actions — gateway doesn't expose session control via /tools/invoke HTTP. Falls back to CLI instructions.

File Operations

Tool	Description
file_read	Read full or partial file contents. Supports start_line/end_line slicing.
file_write	Create or overwrite files. Auto-creates parent directories.
file_edit	Replace a unique string in a file with another. No shell escaping.
file_search	Recursive directory search for literal string patterns. Case-insensitive.

System & CLI

Tool	Description
openclaw_cli	OpenClaw CLI operations. config_get reads filesystem directly (~16ms via JSON5 parse). config_set/doctor/version use SSH to proot. restart returns manual instructions.
shell_exec	Execute arbitrary shell commands on the Termux device. Safety blocklist for destructive patterns.
system_health	Device snapshot: RAM, CPU load, disk, gateway reachability, active processes.

---

Quick Start (Local stdio via SSH)

1. Clone & Build on the device

   git clone https://github.com/schmosbyy/openclaw-mcp-termux.git
   cd openclaw-mcp-termux
   npm install && npm run build
   

2. Create .env in the project root

   cat > .env << 'EOF'
   OPENCLAW_URL=http://127.0.0.1:18789
   OPENCLAW_GATEWAY_TOKEN=your-gateway-bearer-token
   OPENCLAW_HOOK_SECRET=your-hook-secret
   EOF
   

3. Configure Claude Desktop (claude_desktop_config.json)

   {
     "mcpServers": {
       "flip": {
         "command": "/usr/bin/ssh",
         "args": [
           "flip",
           "/data/data/com.termux/files/usr/bin/node /data/data/com.termux/files/home/openclaw-mcp-termux/dist/index.js"
         ]
       }
     }
   }
   

No inline env vars needed — .env is loaded from the project directory automatically.

---

Remote HTTP Mode (Claude.ai)

1. Start the bridge

   bash scripts/gen-token.sh   # generates BRIDGE_TOKEN
   bash scripts/start-tmux.sh  # persistent background
   

2. Expose via Cloudflare

   cloudflared tunnel --url http://127.0.0.1:3000
   

3. Add the tunnel URL + BRIDGE_TOKEN in Claude.ai → Settings → Integrations.

---

Environment Variables

Variable	Required	Description
OPENCLAW_GATEWAY_TOKEN	Yes	Gateway bearer token from openclaw.json (gateway.auth.token). Hex format. Not the device operator token from paired.json.
OPENCLAW_HOOK_SECRET	Yes	Webhook secret for /hooks/agent (async dispatch).
OPENCLAW_URL	No	Gateway URL (default http://127.0.0.1:18789)
BRIDGE_TOKEN	HTTP mode	Auth token for remote Claude.ai connections
OPENCLAW_TIMEOUT_MS	No	HTTP timeout (default 660000ms)
TRANSPORT	No	stdio or http (default stdio)

---

Project Structure

src/
├── index.ts              # Entry point, transport selection, .env loading
├── server.ts             # MCP tool registry (10 tools) + dispatch router
├── transport.ts          # stdio vs StreamableHTTP transport
├── auth.ts               # Bearer token auth for HTTP mode
├── gateway/
│   ├── client.ts         # GatewayClient — HTTP API + SSH CLI
│   └── types.ts          # TypeScript response interfaces
└── tools/
    ├── agent_dispatch.ts  # Send to agents (async/sync/spawn)
    ├── agent_query.ts     # Observe agents (health/sessions/actions/logs/history)
    ├── agent_control.ts   # Control sessions (abort/steer/compact/reset)
    ├── openclaw_cli.ts    # CLI ops (config_get via FS, config_set via SSH)
    ├── file_read.ts       # Read files
    ├── file_write.ts      # Write files
    ├── file_edit.ts       # Edit files (string replace)
    ├── file_search.ts     # Search files
    ├── shell_exec.ts      # Shell commands
    └── system_health.ts   # Device health snapshot

---

Troubleshooting

Issue	Resolution
Cannot find module	Run npm run build. For clean rebuild: rm -rf dist/ && npm run build (tsc doesn't remove stale files).
Server dies after screen lock	Run via bash scripts/start-tmux.sh (claims termux-wake-lock)
Auth failures	Check .env has the correct OPENCLAW_GATEWAY_TOKEN — must match gateway.auth.token in openclaw.json, NOT the device operator token from paired.json.
Gateway unreachable	Start it on the device: ~/bin/openclaw-proot.sh inside Termux
ssh proot fails from MCP tools	SSH tunnel dies with gateway. Restart gateway to restore.