xgw

A CLI tool and daemon that acts as a communication gateway between AI agents and external peers — routing inbound messages from channels (e.g. Telegram) to agent inboxes, and delivering outbound replies back to the right peer.

How it works

• Configure channels (external messaging platforms), agents (inbox paths), and routing rules in a YAML config file.
• Start the daemon with xgw start — it listens for inbound messages on each channel and routes them to the matching agent's inbox via thread push.
• When an agent replies, xgw send delivers the message back to the peer on the correct channel.
• Routing rules map channel + peer → agent; peer: "*" catches all peers on a channel.

Install

From npm

npm install -g @theclawlab/xgw

From source

npm run build && npm link

Quick start

# Start the daemon
xgw start

# Add a channel
xgw channel add --id telegram --type tui

# Register an agent inbox
xgw agent add --id my-agent --inbox ~/.theclaw/agents/my-agent/inbox

# Add a routing rule (all telegram peers → my-agent)
xgw route add --channel telegram --peer "*" --agent my-agent

# Check daemon status
xgw status

# Send a message to a peer
xgw send --channel telegram --peer user42 --session s1 --message "hello"

# Stop the daemon
xgw stop

Commands

Command	Description
xgw start	Start the gateway daemon (background by default)
xgw stop	Stop the daemon
xgw reload	Hot-reload config (SIGUSR1)
xgw status	Show daemon status and active channels
xgw channel add	Add a channel
xgw channel remove	Remove a channel
xgw channel list	List channels
xgw channel pair	Pair/authenticate a channel
xgw channel health	Check channel health
xgw agent add	Register an agent inbox
xgw agent remove	Unregister an agent
xgw agent list	List registered agents
xgw route add	Add a routing rule
xgw route remove	Remove a routing rule
xgw route list	List routing rules
xgw send	Send a message to a peer via a channel
xgw config check	Validate the config file

Data directory

Default: ~/.local/share/xgw/ — override with XGW_HOME.
Config file default: ~/.config/xgw/config.yaml — override with XGW_CONFIG or --config.

$XGW_HOME/
├── logs/    # daemon logs
└── xgw.pid  # daemon lock file

Dependencies

Requires the following tools to be installed and on PATH:

• thread — event queue CLI (used to push messages into agent inboxes)

Documentation

• USAGE.md — full CLI reference, config format, and routing details