praes-connect

One-command observability for OpenClaw agents. Zero code changes needed.

Install

npx praes-connect --key <your-key>

Or install globally:

npm i -g praes-connect
praes-connect --key <your-key>

What it does

praes-connect hooks into your OpenClaw agent and automatically forwards everything to the Praes dashboard:

• Activity — every conversation across all channels
• Costs — tokens, model usage, and spend per run
• Tools — every tool call your agent makes
• Soul — syncs SOUL.md from your workspace
• Memory — syncs MEMORY.md from your workspace

Getting your key

1. Open the Praes dashboard
2. Go to your agent's Console tab
3. Click Connect and copy the key

Options

| Flag | Description | Default | |------|-------------|---------| | --key <key> | Your Praes agent key (required) | — | | --url <url> | Praes server URL | https://praes.app | | --channel <name> | Force a specific channel for all runs | auto-detected |

You can also set PRAES_URL as an environment variable instead of passing --url.

Connecting agents & agent naming

praes-connect auto-selects the OpenClaw agent directory for your Praes agent key. It matches using the Praes slug and name against OpenClaw agent IDs and directory aliases.

Matching order:

1. Exact/normalized match against OpenClaw agents.list metadata (id, name, slug, agentDir) in ~/.openclaw/openclaw.json
2. Exact/normalized match against directory names under ~/.openclaw/agents/
3. Fallback to main (then first available directory)

~/.openclaw/agents/
  my-agent/          ← OpenClaw agent directory name
    sessions/
    ...

Example: if your OpenClaw agent ID/folder is clawdius and your Praes slug is clawdius, the connector auto-binds to ~/.openclaw/agents/clawdius/sessions/ even when multiple agents exist.

Running multiple agents

Each agent in Praes gets its own key. Run a separate praes-connect process per agent:

# Terminal 1 — telegram bot
npx praes-connect --key pk_bot1_xxx

# Terminal 2 — rabbit r1 agent
npx praes-connect --key pk_r1_xxx --channel "rabbit r1"

For best auto-matching, keep each Praes agent slug aligned with the OpenClaw agentId (directory name).

Forcing a channel

If your agent's sessions don't carry platform metadata (common with Rabbit R1, iMessage, and local setups), use --channel to pin it:

npx praes-connect --key pk_xxx --channel "rabbit r1"
npx praes-connect --key pk_xxx --channel telegram
npx praes-connect --key pk_xxx --channel imessage

Supported channel values: telegram, whatsapp, discord, slack, signal, webchat, imessage, rabbit r1, local, api, schedule.

Auto-detection order

When --channel is not set, the channel is resolved in this order:

1. Explicit channel / platform / source field on the JSONL entry
2. Nested metadata or context fields on the entry or message
3. sessions.json hints (channel, origin, Provider) keyed by sessionId
4. OpenClaw canonical session-key patterns (agent:<agentId>:<channel>:..., cron:..., hook:..., node-...)
5. Session ID prefix (e.g. tg_, discord_, r1_, wa_)
6. Content markers in the message (e.g. [voice], [scheduled], rabbit r1, Telegram topic markers)
7. Entry type field (schedule, webhook, cron, etc.)
8. gateway field in ~/.openclaw/openclaw.json
9. Falls back to api

How it works

1. Verifies your key against the Praes API
2. Locates your OpenClaw workspace (~/.openclaw/workspace)
3. Syncs SOUL.md and MEMORY.md to the dashboard
4. Watches ~/.openclaw/agents/<name>/sessions/ for new activity
5. Forwards conversations, tool calls, and cost data in real time
6. Sends heartbeats so the dashboard knows your agent is online

Requirements

• Node.js 18+
• An OpenClaw agent running locally
• A Praes account with an agent key

License

MIT