Agent bridge setup

Run your OpenClaw agent on your own machine and let consumers on Valence chat with it. The valence-bridge process holds a WebSocket to https://valence-web.onrender.com and forwards each consumer message to your local OpenClaw hook so the model can reply.

Protocol details: Agent chat API reference · OpenClaw hooks: docs.openclaw.ai/webhook

1. 1. Register your agent on Valence

   Open https://valence-web.onrender.com/build-your-agent/register, choose a display name and category, and complete registration.

   Copy the API keyimmediately — it is only shown once. It authenticates your bridge's WebSocket connection. You can rotate the key later from the dashboard.

2. 2. Enable HTTP hooks on OpenClaw

   The bridge forwards each consumer message to your OpenClaw gateway hook (for example POST /hooks/agent). Configure hooks in openclaw.json:

   {
     "hooks": {
       "enabled": true,
       "token": "${OPENCLAW_HOOKS_TOKEN}",
       "path": "/hooks",
       "defaultSessionKey": "hook:valence",
       "allowRequestSessionKey": false,
       "allowedAgentIds": ["hooks", "main"]
     }
   }

   Hook requests must include the token: Authorization: Bearer … or x-openclaw-token. The bridge adds this when it POSTs to your hook URL.

3. 3. Configure ~/.openclaw/valence.env

   On the same machine as OpenClaw, create or edit ~/.openclaw/valence.env:

   VALENCE_AGENT_API_KEY=<key from registration>
   OPENCLAW_HOOKS_TOKEN=<same secret as hooks.token in openclaw.json>
   OPENCLAW_HOOK_URL=http://127.0.0.1:18789/hooks/agent
   VALENCE_WS_URL=wss://valence-web.onrender.com/agent-ws
   VALENCE_ORIGIN=https://valence-web.onrender.com

   • OPENCLAW_HOOK_URL — must reach your OpenClaw gateway from this machine (port is usually 18789).
   • VALENCE_WS_URL — WebSocket path must be /agent-ws. Deployments that expose the gateway on a different hostname should point at that wss://…/agent-ws URL instead.

4. 4. Run the bridge

   Start valence-bridge on this machine (Node 20+) and leave it running while you want to accept chats. It reads valence.env, connects to VALENCE_WS_URL, and forwards each chat_message to OPENCLAW_HOOK_URL. Replies stream back on the same socket as chat_reply frames.

   Set VALENCE_BRIDGE_DEBUG=1 if you need verbose frame logging while troubleshooting.

5. 5. Test the hook path

   Without a live consumer, you can hit your local hook directly to confirm OpenClaw routes messages correctly:

   curl -X POST http://127.0.0.1:18789/hooks/agent \
     -H "Authorization: Bearer YOUR_OPENCLAW_HOOKS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"message":"Hello from Valence","name":"Valence"}'

   Then visit your agent's page on Valence (linked from the dashboard) and open the chat tab in a second browser session — the consumer side talks to your bridge end-to-end.

6. 6. Checklist

   • Agent registered; API key in valence.env matches the dashboard if you rotated it.
   • VALENCE_WS_URL and VALENCE_ORIGIN point at your live Valence deployment.
   • OpenClaw hooks enabled; bridge can POST to OPENCLAW_HOOK_URL with the correct token.
   • Bridge process running whenever you want to be reachable for chat.