Crabwalk: A Live Node Graph for OpenClaw Agents

The gap Crabwalk fills: watching agents you cannot see

An OpenClaw agent answering messages on WhatsApp, Telegram, Discord and Slack produces activity that is spread across four chat surfaces and one gateway process. The README describes Crabwalk as a real-time companion monitor for those agents, and the feature list is explicit about the target: a live activity graph of agent sessions and action chains, with thinking states, tool calls and response chains shown as they happen. That is a narrow audience. If you run one agent on one platform and read its logs, a graph adds little. If you run agents across several messaging platforms and want to know which session is currently calling which tool with which arguments, the flat log stops being readable. Crabwalk is built for that second case, and the session filtering (by platform, by recipient search) confirms the assumption that more than one session is usually in flight.

How the monitor gets its data: gateway socket to ReactFlow

The data path in the README is short. Crabwalk opens a WebSocket connection to the OpenClaw gateway, defaulting to ws://127.0.0.1:18789, and streams events from it. Those events become nodes in a ReactFlow graph; expanding a node reveals tool arguments and payloads. A node graph is the right shape for this because agent work is a chain rather than a sequence of independent lines: one session spawns a tool call, the tool call returns, the response goes back out to a platform. Stack details back this up. The project is TypeScript and lists TanStack Start, ReactFlow, Framer Motion, tRPC and TanStack DB. ReactFlow is the rendering layer; tRPC and TanStack DB sit between the socket and the UI. Nothing in the supplied material describes a database, a replay buffer, or a server-side store of past sessions, so treat the graph as a live view. If you close the tab, the README gives no indication that the history is waiting when you return.

Installation paths: agent skill, CLI tarball, Docker, source

There are four ways in, and they differ in how much you maintain. The README's first option is to hand an OpenClaw agent the skill URL (https://raw.githubusercontent.com/luccast/crabwalk/master/public/skill.md) and ask it to install or update Crabwalk. The second is a CLI install that resolves the latest release tag from the GitHub API, extracts crabwalk-${VERSION}.tar.gz into ~/.crabwalk, copies the binary to ~/.local/bin and marks it executable. The third is Docker, which the README calls recommended: docker run -d with -p 3000:3000, -e CLAWDBOT_API_TOKEN=your-token and -v ~/.openclaw/workspace:/root/.openclaw/workspace against ghcr.io/luccast/crabwalk:latest. The fourth is from source: git clone, npm install, then CLAWDBOT_API_TOKEN=your-token npm run dev, with the monitor at http://localhost:3000/monitor. The CLI itself is small: crabwalk starts the server on 0.0.0.0:3000, crabwalk start --daemon backgrounds it, and stop, status and update manage the process. Flags cover the obvious knobs: -p/--port, -H/--host, -g/--gateway, -t/--token, -d/--daemon. On startup it prints a QR code for opening the monitor on a phone, which requires qrencode; the README says the installer adds it automatically.

Token handling and the loopback binding trap

Configuration is deliberately thin. The CLI reads ~/.openclaw/openclaw.json and pulls the token from gateway.auth.token, so a local setup needs no flags at all. To check by hand: jq '.gateway.auth.token' ~/.openclaw/openclaw.json. To override, pass crabwalk -t your-token or export CLAWDBOT_API_TOKEN. The interesting constraint is networking. The README notes that when Crabwalk runs in Docker, the gateway typically runs on the host, so the container should point at ws://host.docker.internal:18789. Then it adds a sharper caveat: if OpenClaw is configured with bind: loopback and you use tailscale serve for tailnet-only access, the container must run with host networking, replacing -p 3000:3000 with --network host, so the container can reach 127.0.0.1:18789 while keeping loopback-only binding. That is a real trade-off, not a footnote. Host networking removes the port isolation Docker would otherwise give you, and the README presents it as the price of not widening the gateway's bind address. If your security posture depends on the gateway never listening beyond loopback, this is the decision you have to make before installing anything.

Workspace access is a filesystem mount, not an API

Crabwalk added workspace file editing in v1.0.11, and the README explains what that means for deployment: the workspace explorer reads local files, looking by default at ~/.openclaw/workspace. In Docker you mount the host directory to the same path inside the container, either the default -v ~/.openclaw/workspace:/root/.openclaw/workspace or a custom host path mapped to that same container path. With docker-compose, the WORKSPACE_HOST_PATH environment variable sets the host side. The consequence is worth stating plainly: the container needs write-capable access to the directory where your agent keeps its files, because the feature is editing, not just reading. Anyone evaluating Crabwalk should treat that mount as the main blast-radius question, more than the token. The token authenticates to the gateway; the mount hands the monitor your agent's working files.

What Crabwalk does not do

The README describes a monitor, and that word is accurate. There is no mention of sending messages, approving tool calls, or interrupting a running session from the graph. You watch; you do not steer. The second limitation is historical depth. The stated mechanism is a WebSocket connection to the gateway with live streaming, and no persistence layer appears anywhere in the stack list or the configuration section. A session that finished before you opened the browser is not described as recoverable. Third, the setup assumes a gateway you can reach from the machine running Crabwalk, with a token you can read from a local JSON file. There is no described path for monitoring someone else's gateway, no user accounts, and no multi-tenant separation. If your agents run on a shared host and several people need dashboards, this is the wrong tool, and the Docker networking section suggests the project expects a single operator on a trusted network rather than a hosted service. Finally, the releases shown (v1.0.9 through v1.0.11, spanning early February 2026) are all 1.0.x patch releases, the latest titled Workspace File Editing and the one before it User Feedback System. A 1.0.x line shipping feature work in patch versions is a signal about how the project versions, not about whether it works.

The alternative: reading the gateway directly

The obvious alternative is to skip the graph and consume the gateway yourself. Crabwalk's own configuration section shows how little is involved on the client side: a WebSocket URL and a bearer token from gateway.auth.token. Anything that speaks WebSocket can subscribe to the same stream, which means a small script or an existing log pipeline can capture the same events. The difference is in what you get back. A raw subscriber gives you events in arrival order with no session grouping, no cross-platform filtering, no expandable tool payloads, and no visual distinction between a thinking state and a completed response. Crabwalk's contribution is the ReactFlow rendering plus the session model layered on top of the socket, and the README's feature list (filter by platform, search by recipient, expand nodes to inspect args) is really a description of that layer. If your need is archival or alerting, a subscriber plus your existing tooling is the leaner choice. If your need is watching several concurrent sessions and understanding which one is doing what right now, rebuilding the graph layer is the work you would be avoiding.

Maintenance cost and licence

The project ships as a single binary through GitHub release tarballs, with crabwalk update as the built-in upgrade path, and as a Docker image at ghcr.io/luccast/crabwalk:latest. That is two upgrade surfaces to keep in mind: the binary you copied into ~/.local/bin, and the image tag, which is latest rather than a pinned version. Pinning the image to a specific tag is possible given the release naming, and worth considering if you want upgrades to be deliberate rather than automatic. The install script resolves the newest release tag at run time, so a fresh install always lands on the current version, which is convenient and also means the install command is not reproducible unless you pin VERSION yourself. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included; that is a summary of the licence's usual terms, not legal advice, and you should read the LICENSE file in the repository if the distinction matters to your organisation. There is no described hosted tier, account system or paid component in the supplied material, so there is no vendor relationship to maintain beyond the repository itself.

Editorial conclusion

Adopt Crabwalk if you already run an OpenClaw gateway locally and want to watch multi-platform agent sessions as a graph rather than reading logs. Skip it if you need a remote multi-tenant dashboard, if you cannot expose the gateway socket to the container, or if you want to replay past sessions, since nothing in the README describes persistence or historical playback. Before committing, verify three things on your own machine: that jq '.gateway.auth.token' ~/.openclaw/openclaw.json returns a token the CLI can pick up, that the gateway actually answers on ws://127.0.0.1:18789, and that a test container can reach the host socket with host networking enabled.

Official sources

1. crabwise-ai/crabwalk on GitHub
2. License: MIT
3. Project website
4. README
5. Releases