Skip to main content
Glama
Sign In
openclaw-mcp-termux

openclaw-mcp-termux

by schmosbyy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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

Related MCP server: Android MCP Server

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.

Available Tools

10 tools
agent_controlA

Control running agent sessions: abort stuck agents, steer them in a new direction, compact their context, or reset them. Uses the gateway /tools/invoke API. If the gateway does not support a given action, returns a clear error with CLI fallback instructions.

Inputs: action (required), sessionKey (required), message.

agent_dispatchA

Send a task or message to an OpenClaw agent. Three modes:

  • "async" (default): fire-and-forget via webhook. Returns immediately with accepted status. Supports delivery to Telegram.

  • "sync": wait for agent reply via chat completions. Blocks until response.

  • "spawn": tracked sub-agent delegation via /sessions_spawn. Returns runId + childSessionKey for observation. Routes to Tani (main), Alan (coding), or Rachel (rachel). Only call when the user has explicitly requested execution.

Inputs: message (required), to, mode, name, +10 more.

agent_queryA

Multi-view agent observation. Consolidates health checks, session listings, activity monitoring, and log access into a single tool.

  • "health": gateway reachability (~38ms)

  • "sessions": all agent sessions with metadata from sessions.json + JSONL

  • "actions": active processes, recently-modified sessions, recent tool calls, log tail

  • "logs": gateway/command/heartbeat log scenarios

  • "history": JSONL transcript read for a specific session

Inputs: view (required), tail, scenario, agent_ids, +3 more.

file_editA

Replace a unique string in a file with another string. old_str must match the raw file content exactly and appear exactly once. Use this instead of shell-based sed/python for all file edits — content goes through JSON parameters, never a shell, so there are no escaping issues.

Inputs: path (required), old_str (required), new_str.

file_readA

Read an entire file or a specific line range. Content comes back through JSON — no shell, no escaping issues. Use start_line / end_line for large files. Output is capped at 2000 lines.

Inputs: path (required), end_line, start_line.

file_searchA

Search for a literal string pattern in a file or recursively in a directory. Returns structured hits with surrounding context lines. Case-insensitive. Replaces grep -n. For regex searches, use shell_exec.

Inputs: path (required), pattern (required), max_results, context_lines, +1 more.

file_writeA

Create or overwrite a file with the given content. Content goes through JSON parameters — never a shell — so there are no escaping or newline-stripping issues. Automatically creates parent directories if they do not exist. Use this for new files and full rewrites. For targeted edits to existing files, use file_edit instead.

Inputs: path (required), content (required).

openclaw_cliA

OpenClaw CLI operations: read/write config, run doctor, check version, restart instructions.

  • "config_get": reads openclaw.json directly from filesystem (~16ms, no CLI overhead). Supports dot-paths like "agents.list[0].model".

  • "config_set": writes via CLI over SSH (slower but safe — CLI handles validation and env var resolution).

  • "doctor": runs openclaw doctor via SSH.

  • "version": returns the installed OpenClaw version.

  • "restart": returns manual restart instructions (gateway cannot be restarted remotely).

Inputs: command (required), fix, key, value, +1 more.

shell_execA

Execute arbitrary shell commands on the Termux device. Useful for direct filesystem inspection and diagnostics. Only call when the user has explicitly requested execution, or when diagnostics are clearly required for the task at hand. Do not use for speculative exploration or as a default first step.

Inputs: command (required), cwd, timeout.

system_healthA

Snapshot of Termux device health: RAM, CPU load, disk space, OpenClaw version, gateway reachability, and active OpenClaw/node processes. Fast and read-only — safe to call any time.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 10 tools

    Disambiguation4/5

    Each tool has a clear primary job, and the agent_* and file_* prefixes separate control, observation, and execution well. Minor overlap exists between agent_query's health/log views and system_health's gateway/process snapshot, but the descriptions are specific enough to prevent serious misselection.

    Naming Consistency4/5

    Names are consistently snake_case and mostly follow a verb_noun pattern like agent_dispatch, file_read, and shell_exec. openclaw_cli and system_health are noun-style deviations, but the overall pattern remains predictable and readable.

    Tool Count5/5

    10 tools is well-scoped for an OpenClaw-on-Termux server: four agent-management tools, four file tools, plus shell execution and system health. Each tool has a distinct role with no obvious redundancy.

    Completeness4/5

    The surface covers agent dispatch, observation, control, configuration/diagnostics, file CRUD/search, and device health. Minor gaps like no remote gateway restart and no direct configured-agent listing are workable and do not create dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers