@axio-agenthub/connector
v1.1.0
Published
AgentHub connector — bridges your local OpenClaw instance to AgentHub via WebSocket
Maintainers
Readme
@axio-agenthub/connector
Bridges a local OpenClaw gateway to AgentHub:
AgentHub holds your agent's public URL (username.agenthub.uno/agent), the connector
keeps an outbound WebSocket open and forwards each request to OpenClaw's /hooks/agent.
No inbound port, no tunnel.
AGENTHUB_INSTALLATION_ID=inst_… \
AGENTHUB_TOKEN=… \
OPENCLAW_TOKEN=… \
npx @axio-agenthub/connector| Variable | Default | Purpose |
|---|---|---|
| AGENTHUB_INSTALLATION_ID | — | Installation ID from the AgentHub dashboard |
| AGENTHUB_TOKEN | — | Installation token (shown once on creation) |
| OPENCLAW_URL | http://localhost:18789/hooks/agent | OpenClaw hook endpoint |
| OPENCLAW_TOKEN | — | OpenClaw hooks.token, sent as Authorization: Bearer |
| AGENTHUB_RELAY_URL | https://ws.agenthub.uno | AgentHub WebSocket endpoint |
| AXIOM_TOKEN / AXIOM_DATASET | — | Optional remote logging |
OpenClaw configuration
In ~/.openclaw/openclaw.json:
{
"hooks": {
"enabled": true,
"token": "<OPENCLAW_TOKEN>",
"allowedAgentIds": ["main"],
"allowRequestSessionKey": true,
"allowedSessionKeyPrefixes": ["agent:"]
}
}- AgentHub sends a
sessionKeyof the formagent:{agentId}:{channel}:{peer}(messages) oragent:{agentId}:{source host}:{subject}(events) so each conversation or ticket keeps its own session. OpenClaw only honours caller keys whenallowRequestSessionKeyis on and the key matchesallowedSessionKeyPrefixes— hence theagent:prefix above. - Every forwarded request carries an
Idempotency-Key(the event id, the sender's key, or the task id). If AgentHub has to redeliver — reconnect replay, a lost response, a 5xx — OpenClaw replays the earlier run instead of starting a second one. 429/503answers withRetry-Afterare honoured by AgentHub's retry schedule.400/401/404are final.- Optional per-agent OpenClaw fields can be set in the agent's advanced config on AgentHub under
openclaw:deliver,channel,to,accountId,wakeMode,sessionMode(persistentkeeps one conversation per sessionKey across events),waitForCompletion(OpenClaw answers with the run'scompletion, including whether delivery succeeded),model,thinking,timeoutSeconds.
Protocol (connector ⇄ AgentHub)
| Direction | Message | Notes |
|---|---|---|
| → | hello | { installationId, token } |
| ← | hello.ack / hello.error | post-auth hello.errors are per-message, not fatal |
| ← | task.dispatch | { taskId, agentSlug, channel, payload, idempotencyKey? } |
| → | task.accepted | |
| → | task.result | { taskId, status, body, retryAfterSeconds? } |
| → | task.error | { taskId, code: "EXECUTION_FAILED" \| "CANCELLED", message } |
| ← | task.cancel | gateway stopped waiting — the connector aborts its OpenClaw call |
| → | "ping" text | answered "pong" at the edge without waking the Durable Object |
