OpenClaw IM Bridge 🌉

English | 繁體中文

A lightweight, host-agnostic bridge that connects your local OpenClaw Gateway to Instant Messaging platforms (like Telegram).

This tool brings Interactive Approvals and System Monitoring directly to your phone. Whenever your AI agent (Gemini/Claude) needs to execute a dangerous shell command, instead of checking the web dashboard, you get an instant push notification with [✅ Approve] and [❌ Reject] buttons.

---

✨ Features

• Interactive Execution Approvals: Get inline buttons in Telegram to allow or deny shell commands requested by your Agent.
• Real-time Status Dashboard: Send /sysinfo to get a beautifully formatted Markdown report of your host machine's CPU, Memory, and Uptime.
• Bridge Health Check: Send /status to verify the WebSocket connection to your OpenClaw Gateway.
• Zero-Config Integration: Runs alongside OpenClaw. No modifications to your existing agents or plugins required.
• Self-Healing: Automatically reconnects to the Gateway if the connection is dropped, with ws.terminate() ensuring clean reconnection on WebSocket errors.
• Authorized-Only Callbacks: Telegram callback queries (button presses) are validated against your TELEGRAM_CHAT_ID, preventing unauthorized users from approving commands.

---

💡 Why this project?

Most LLM bots require you to switch to their specific framework. OpenClaw IM Bridge is different:

• Non-Intrusive: It runs alongside your existing OpenClaw setup. No need to change your Agent prompts or modify core config files.
• Mobile-First Security: Why open a web dashboard on your desktop when you can approve a dangerous command with a single tap on your phone?
• Lightweight Microservice: It communicates purely via WebSocket RPC, making it extremely stable and decoupled from the main Agent logic.

🚀 Getting Started (Step-by-Step for Beginners)

This tool is a "companion" for your OpenClaw system. Follow these steps to set it up:

1. Prerequisites

• Install Node.js: Download and install from nodejs.org.
• Have OpenClaw running: Make sure your OpenClaw gateway is already active on your machine.

2. Get your Keys

• OpenClaw Token: Open your .openclaw/openclaw.json file. Look for the gateway.auth.token field. Copy that long string.
• Telegram Token: Ask @BotFather for a /newbot to get your Token.
• Your ID: Ask @userinfobot for your user ID.

3. Setup

1. Download this project as a ZIP and unzip it.
2. Open terminal/cmd, cd into the folder.
3. Run: npm install
4. Create a .env file and paste your Token and ID (see .env.example).
5. Run: node index.js

---

🚀 Installation (Advanced)

1. Clone the repository

git clone https://github.com/Harperbot/openclaw-im-bridge.git
cd openclaw-im-bridge

2. Install dependencies

npm install

3. Configuration

Copy the example environment file:

cp .env.example .env

Edit the .env file with your details:

# OpenClaw Gateway URL (usually ws://127.0.0.1:18789)
GATEWAY_URL=ws://127.0.0.1:18789

# Your OpenClaw Gateway Auth Token
# (Found in ~/.openclaw/openclaw.json under gateway.auth.token)
GATEWAY_TOKEN=your_openclaw_gateway_token

# Telegram Bot Token (from @BotFather)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

# Your personal Telegram Chat ID (to ensure only YOU can approve commands)
TELEGRAM_CHAT_ID=your_chat_id

4. Run the Bridge

Start the bridge manually:

node index.js

Or run it in the background using PM2:

npm install -g pm2
pm2 start index.js --name "openclaw-bridge"
pm2 save

🎮 Usage

Once running, open your Telegram bot and try the following commands:

• /sysinfo - View host hardware status (Memory, Uptime, CPU Architecture).
• /status - View OpenClaw Gateway connection status and pending approvals.

When OpenClaw intercepts a dangerous command execution, the bot will automatically send a message:

🛠️ OpenClaw Approval Request Agent: main Command:

rm -rf /tmp/cache

[ ✅ Approve Once ] [ ❌ Reject ]

🏗️ Architecture

This bridge uses a Host-Agnostic design. It connects to the OpenClaw WebSocket RPC interface (ws://127.0.0.1:18789) just like the official Control UI does.

1. It authenticates using your token.
2. It polls/listens for exec.approvals.get and exec.approval.requested events.
3. It relays decisions back via the exec.approval.resolve RPC method.

🤝 Contributing

Pull requests are welcome! If you want to add adapters for Discord, Slack, or Feishu, please open an issue first to discuss the architecture.

📜 License

MIT