How IMClaw Turns Any AI Agent into a Remote Service with the ACP Protocol

IMClaw is an open‑source AI‑Agent gateway that supports the ACP (Agent Client Protocol). It enables developers to control AI coding assistants such as Claude, Codex, Gemini, and many others through instant‑messaging tools (WeChat, Feishu, Telegram, etc.) or directly from remote servers.

Why IMClaw?

Developers often face three main problems when using AI assistants on remote machines:

Running an AI assistant on a remote server requires manual SSH login and environment setup.

Each AI agent has its own CLI and configuration, making unified management difficult.

Exposing an AI agent to the network raises security concerns.

IMClaw addresses these issues by providing a unified gateway that abstracts the agents behind a single protocol.

ACP Protocol Overview

The ACP protocol standardizes communication between a client and any AI agent. It defines a unified message format, session handling, permission requests, and tool invocation, allowing multiple agents to be accessed with the same API.

Standardized message format : Requests, responses, and errors share a common JSON‑RPC structure.

Session management : Multiple rounds of conversation can be kept in context.

Permission control : Sensitive actions (file write, command execution) require explicit approval.

Tool use : Agents can call predefined tools such as file read/write, Bash commands, grep, and glob patterns.

Supported AI Agents

pi

– Pi Coding Agent (adapter pi-acp) openclaw – OpenClaw ACP bridge codex – Codex CLI claude – Claude Code gemini – Gemini CLI cursor – Cursor CLI copilot – GitHub Copilot CLI droid – Factory Droid iflow – iFlow CLI kilocode – Kilocode kimi – Kimi CLI kiro – Kiro CLI opencode – OpenCode qoder – Qoder CLI qwen – Qwen Code trae – Trae CLI

acpx – The ACP Command‑Line Tool

acpx is a Node.js CLI that implements the ACP protocol, acting as an "Agent router". It can be installed globally and used to interact with any supported agent. npm install -g acpx@latest Key capabilities:

Multi‑Agent support : Claude, Codex, and any other ACP‑compatible agents.

Session management :

# Create a new session
acpx session create --name my-session
# List sessions
acpx session list
# Use a specific session
acpx prompt --session my-session "Analyze this code"

Tool integration (built‑in tools): Read – read file contents Write – write file contents Bash – execute shell commands Grep – search file contents Glob – file pattern matching

Permission modes : approve-reads (default) – reads auto‑approved, writes require confirmation. approve-all – all actions auto‑approved (use with caution). deny-all – read‑only mode, all write operations denied.

IMClaw Core Features

🚀 Remote access : Connect to AI agents on any server via a single WebSocket endpoint.

🔐 Secure authentication : Token‑based access control.

💬 Multi‑session management : Sessions persist across connections.

🤖 Multi‑Agent support : Switch between Claude, Codex, Gemini, etc., with one command.

⚡ Lightweight deployment : A single binary without configuration files.

Architecture

┌─────────────┐          ┌─────────────┐          ┌─────────────┐
│ imclaw-cli  │ ◄──────► │   imclaw   │ ◄──────► │   acpx      │
│ (local CLI) │  JSON‑RPC │ (gateway)  │  subprocess │ (AI Agent) │
└─────────────┘          └─────────────┘          └─────────────┘
        ▲                         ▲
        │                         │
        │      Network (cross‑server)      │
        └─────────────────────────────────────┘

Installation

Three installation methods are provided:

Pre‑compiled binary (recommended): Download the appropriate archive from the GitHub Releases page for Linux, macOS, or Windows and extract it.

One‑click script :

curl -fsSL https://raw.githubusercontent.com/smallnest/imclaw/main/scripts/install.sh | bash

Go install (requires a Go environment):

go install github.com/smallnest/imclaw/cmd/imclaw@latest
go install github.com/smallnest/imclaw/cmd/imclaw-cli@latest

Quick Start

Start the gateway on a remote server:

# Default (listens on 0.0.0.0:8080)
imclaw
# Custom port and token
imclaw --port 9000 --token your-secret-token

Connect from a local machine: imclaw-cli --server ws://your-server:8080/ws Enter interactive mode and issue commands, e.g.:

> 帮我分析一下 /var/log/nginx/error.log 里的错误

Or run a single command without entering the REPL:

imclaw-cli --server ws://your-server:8080/ws -p "列出当前目录文件"

Advanced Usage

Session reuse : Preserve context across multiple calls using the --session flag.

Agent switching : Specify --agent claude or --agent codex to target a different backend.

Permission control : Choose --approve-all for full automation or --deny-all for read‑only audits.

Tool restriction : Limit the toolset with --allowed-tools "Read,Grep,Glob".

Working directory : Set --cwd /path/to/project so all file operations are relative to that directory.

acp‑remote Skill for OpenClaw

OpenClaw users can install the acp-remote skill, which wraps imclaw-cli and acpx, allowing direct AI‑driven remote operations from an OpenClaw conversation.

# Install dependencies
npm install -g acpx@latest
curl -fsSL https://raw.githubusercontent.com/smallnest/imclaw/main/scripts/install.sh | bash

Configure environment variables (optional):

export IMCLAW_SERVER="ws://your-server:8080/ws"
export IMCLAW_TOKEN="your-secret-token"

Example usage inside OpenClaw:

使用 acp-remote skill, agent用claude, 获取当前北京的天气

Security Best Practices

Use a strong random token for authentication (e.g., openssl rand -hex 32).

Restrict network exposure: bind to localhost and use SSH tunnels or firewall rules.

Prefer approve-reads or deny-all modes for audit scenarios.

Rotate tokens regularly and store them securely (environment variables or secret files).

Conclusion

IMClaw provides a simple, practical, and secure way to turn any AI coding assistant into a remote service. Its lightweight design, unified ACP protocol, and flexible CLI make it suitable for automation, debugging, code review, and integration with other platforms such as OpenClaw.

The project is fully open‑source and welcomes contributions, stars, and feedback.