ClawApp: a phone-side chat client for an OpenClaw Gateway bound to localhost

The localhost problem ClawApp exists to solve

OpenClaw's Gateway listens on 127.0.0.1:18789 by default. That binding is the whole reason ClawApp exists. A phone on the same WiFi cannot open a socket to a loopback address on your laptop, and even if you rebind the Gateway to 0.0.0.0, the README states that authentication involves an Ed25519 device-signature handshake compatible with OpenClaw 2.13 and later. A mobile browser cannot perform that handshake on its own.

So ClawApp is two things shipped in one repository: a Node server that terminates the browser connection and re-originates an authenticated WebSocket to the Gateway, and a front-end chat client that talks to that server. The target user is someone already running OpenClaw on a home machine or a small server, who wants the agent in a phone browser tab rather than a desktop terminal. It is not a hosted service and not a general-purpose chat UI. If you do not already run an OpenClaw Gateway, there is nothing here for you to connect to.

How the proxy sits between phone and Gateway

The README gives the data flow as a three-hop chain. The phone browser connects over WS or WSS to the ClawApp server on port 3210. That server holds an offline cache and then opens its own WebSocket to the OpenClaw Gateway on port 18789, adding the Ed25519 device signature on the way through. The browser never speaks the Gateway protocol directly.

That indirection is what makes the client portable. Because the proxy owns the handshake, the front end can be a plain web page, a PWA install, or a Capacitor-wrapped Android APK, and all three reuse the same code. The README also notes the proxy serves the H5 chat page itself, so one process covers both the API surface and the static assets. In Docker, the server reaches the host Gateway through host.docker.internal, which is the documented way to keep the Gateway on the host while the proxy runs in a container.

The client-side feature list is longer than the architecture: streaming replies with a typewriter effect, image send and receive, Markdown with code highlighting and XSS protection, a slash-command panel for /model, /think and /new, live tool-call status, multi-agent selection when creating a session, session switching and deletion, light/dark/system themes, Chinese and English UI, and IndexedDB-backed message caching so history survives a disconnect. Reconnection is described as automatic with message deduplication.

Getting it running: install script, Docker, or npm

There are three documented paths. The install script is the shortest: a curl pipe to bash on Mac and Linux, or an irm pipe to iex on Windows PowerShell. The README says the script detects the environment, clones the repository, installs dependencies, builds the front end, prompts for a token interactively, and can run under PM2. It also claims that if OpenClaw is installed locally, the script reads the Gateway token automatically. That last behaviour is convenient and also the kind of convenience worth checking before you run a piped script on a machine that holds credentials.

The Docker path is explicit. Clone the repository, create a .env at the root, and set PROXY_TOKEN to the password your phone will use, OPENCLAW_GATEWAY_TOKEN to the value found in ~/.openclaw/gateway.yaml, or OPENCLAW_GATEWAY_PASSWORD instead. The README states that setting the password variable switches authentication to password mode and takes priority over the token, and that password mode is required for Tailscale Funnel scenarios. Then docker compose up -d --build, with docker compose logs -f to watch it.

The manual path is npm run install:all, npm run build:h5, copy server/.env.example to server/.env, edit the token, then npm start. For a persistent process, the README gives pm2 start server/index.js --name clawapp followed by pm2 save and pm2 startup. To reach it from a phone on the same WiFi, open http://<your-computer-ip>:3210 and enter the server address and token in the login screen. Note the two env file locations: .env at the repository root for Docker, server/.env for the direct npm run.

HTTPS is not optional if you want the microphone

Voice input is listed as a feature, and the README is unusually direct about the catch: speech-to-text needs an HTTPS secure context, so a plain HTTP address on the local network cannot use the microphone. That single constraint reshapes the deployment decision.

The README's preferred answer is cftunnel, a companion CLI that wraps Cloudflare Tunnel. For a throwaway share, cftunnel quick 3210 prints a trycloudflare.com URL with HTTPS already in place. For a stable address, the sequence is cftunnel init, cftunnel create my-tunnel, cftunnel add clawapp 3210 --domain chat.example.com, cftunnel up, and cftunnel install to register it at boot. The trade-off is stated in the project's own comparison table: it depends on Cloudflare's service.

The alternatives are the SSH reverse tunnel (ssh -f -N with -R 0.0.0.0:3210:127.0.0.1:3210), which needs a public server, GatewayPorts yes in sshd_config, and port 3210 open in the firewall, and which the README flags as HTTP-only and therefore without voice input. Nginx reverse proxying gives you HTTPS and a custom domain but requires a certificate and the WebSocket upgrade headers, including proxy_read_timeout 86400 so long-lived streams are not cut. If you are happy without the microphone, the SSH tunnel is the least moving parts. If you want the PWA install and the mic, you need TLS from somewhere.

Where ClawApp is the wrong tool

The clearest failure mode is scope. ClawApp does not make an OpenClaw Gateway reachable to anyone who does not control that Gateway. It is a client, not a relay service, and every deployment option in the README assumes you own the machine running port 18789 and can read its token file. If your agent lives on someone else's infrastructure, this repository does not help.

The second is version coupling. The Ed25519 device-signature handshake is documented as compatible with OpenClaw 2.13 and later. Nothing in the material describes behaviour against older Gateways, so an older install is an untested combination rather than a supported one. Given that the project itself tracks a moving upstream, that coupling is a recurring upgrade concern rather than a one-time setup step.

Third, the deployment surface is real. You are exposing a token-authenticated proxy that can drive an AI agent with tool-calling privileges. The README offers PROXY_TOKEN, OPENCLAW_GATEWAY_TOKEN and ALLOWED_ORIGINS as configuration, and mentions password mode for Tailscale Funnel, but it does not document rate limiting, session expiry or audit logging. For a single-user home setup that may be acceptable. For anything multi-user, the authentication model described here is thin, and you should treat the proxy as something to keep on a private network or behind an identity-aware tunnel rather than on an open port.

Finally, the licence is unknown. The listing shows no licence identifier, so the terms under which you may use, modify or redistribute ClawApp are not established by the material available. Check the repository for a licence file before depending on it.

How this differs from a general chat front end

The obvious comparison is any self-hosted chat UI that speaks to an OpenAI-compatible endpoint. Those tools assume the model is reachable over HTTP with a bearer token, and they render messages. ClawApp assumes the opposite: an agent Gateway that binds to loopback and demands a cryptographic device handshake before it will accept a socket. The proxy exists to satisfy that handshake, not to normalise an API.

That difference shows up in the feature list. Tool-call status, multi-agent session creation, and the /model, /think and /new command panel are all Gateway concepts leaking into the client. A generic chat front end would have no reason to render them. ClawApp's value is precisely that it is not generic: it knows the OpenClaw protocol well enough to expose its controls on a phone screen.

The cost of that specificity is that ClawApp is useful only inside the OpenClaw ecosystem. If you later move your agent to a plain HTTP inference endpoint, the proxy becomes dead weight and a generic web UI would serve you better. Conversely, if you stay on OpenClaw, a generic client cannot replace it, because it cannot complete the handshake. The choice is not between two clients for the same backend. It is between a client built for this protocol and one built for a different one.

Maintenance, upgrades and what the release cadence implies

The release history shows v1.8.1, then v1.9.0, then v2.0.0, with the most recent push and release both dated 2026-05-07. The jump to a major version, combined with the note that device signing targets OpenClaw 2.13 and later, suggests the project tracks upstream Gateway changes rather than pinning to a frozen protocol. Plan for periodic client updates when the Gateway moves.

Operationally, the upgrade cost is low if you used the install script, since it handles cloning, dependency installation and the front-end build. It is higher if you built the H5 bundle yourself, because the front end is compiled with npm run build:h5 and a stale bundle will not pick up server-side changes. Under PM2, the documented restart is a matter of restarting the clawapp process; under Docker, docker compose up -d --build rebuilds the image. Neither path is described as requiring a data migration, and the client-side cache lives in IndexedDB on the phone, so a server upgrade does not touch message history stored there.

The licence question remains open and is the one item that could change the calculus. Without a licence identifier in the listing, you cannot assume permissive terms. Read the repository's licence file, if one is present, before shipping ClawApp as part of anything you distribute.

Editorial conclusion

Adopt ClawApp if your OpenClaw Gateway runs on a machine you control and you want a phone browser client without building one, and if you can put the proxy behind HTTPS (cftunnel or Nginx) so the mic and PWA install work. Do not adopt it if you need a client for a Gateway you do not administer, or if you cannot expose port 3210 at all. Before rolling it out, verify three things: that your OpenClaw version is 2.13 or newer, since the README ties Ed25519 device signing to that line; that OPENCLAW_GATEWAY_TOKEN matches the value in ~/.openclaw/gateway.yaml, or that you have set OPENCLAW_GATEWAY_PASSWORD instead if you are fronting the Gateway with Tailscale Funnel; and that the repository's licence file exists, because the listing shows no licence identifier.

Official sources

1. Issues
2. Project website
3. qingchencloud/clawapp on GitHub
4. README
5. Releases