CLI tool
qingchencloud/clawapp avatar
qingchencloud/clawapp

ClawApp puts a signing proxy between your phone and a loopback-bound gateway

ClawApp is a mobile chat client for the OpenClaw AI agent, with streaming conversation, image sending/receiving, tool calls, and both PWA and APK builds.

447 stars56 forksJavaScriptLicense varies

At a glance

What is it?
ClawApp is a mobile chat client for an agent platform whose gateway listens only on the loopback interface. It runs a proxy on one port that performs the device-signing handshake and caches messages offline, and it ships as a web page, a desktop application, and an Android package, with a feature list whose voice input quietly dictates your tunnel choice.
Who is it for?
ClawApp suits someone whose agent runs on their own machine and who wants to talk to it from a phone without exposing the gateway to a network. It does not suit anyone who needs the voice input on a plain local network, because that feature needs a secure context the local setup cannot provide.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Activity is slowing. The repository last received commits 6 months ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • qingchencloud/clawapp447 ★ · +4
Star history
Repository2026-09-112026-11-15
qingchencloud/clawapp443447

4 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The gateway binds to loopback, so a proxy sits in the middle

The problem statement is one sentence, and everything else in the repository follows from it: the agent platform is capable, but its gateway listens only on the local machine, on a fixed port, so a phone cannot connect to it.

The solution is a three-hop chain. The phone's browser, on any network, opens a WebSocket to a proxy server running on a different port, which holds an offline cache. That proxy opens its own WebSocket to the gateway and performs a device-signing handshake as part of the connection, using a signature scheme the proxy implements so the phone never has to.

Two consequences are worth naming. First, the proxy is not a dumb relay: it terminates the authentication handshake, which means the phone speaks one protocol and the gateway another, and only the proxy has to speak both. Second, the same server hands out the chat page itself, so the whole client is a page served from the machine running the agent. There is nothing to install on the phone.

The handshake is versioned. The documentation states compatibility with a particular minimum version of the agent platform, which is the number to check first if a connection fails after an agent upgrade.

Two authentication paths, and password mode wins

The proxy has its own credential, separate from the agent's.

The client is asked for exactly two things when it opens: the address of the machine running the proxy, and a token. The address is either a local network address with the proxy port, or whatever public address or generated domain your tunnel produced.

Upstream, the proxy authenticates to the agent gateway in one of two ways. A gateway token is the default, and the documentation says where to find it, which is a configuration file inside the agent's own directory rather than anything the proxy knows. A gateway password is the alternative, and setting it switches the proxy to password authentication automatically, taking priority over the token.

That priority rule is not cosmetic. The documentation states the password mode is mandatory in the one scenario where a token cannot work, which is exposure through a hosted tunnelling service.

The offline cache is the other half of the resilience story. Messages persist in the browser's own local database, so history is readable with no network, and the client syncs once connectivity returns. Reconnection is handled with deduplication, so a dropped connection during a long agent run does not produce duplicate turns.

Voice input is the feature that picks your tunnel

One line in the remote-access section explains the whole tunnelling section, and it is easy to skim past.

Browser speech recognition requires a secure context. A page served over plain HTTP on a local network cannot open a microphone, so the voice input feature listed in the feature table simply does not work in the local setup.

That turns tunnel choice into feature choice, and the documentation is direct about it. The recommended tool is a one-command manager for a hosted tunnel service, which is free, provides HTTPS automatically, needs no public address on your machine, and can be registered to start at boot. For temporary sharing it needs no configuration at all; for a fixed domain it needs an account and a domain you own, after which it creates the DNS record itself.

The other options are documented with the same honesty about cost. An SSH tunnel needs a server with a public address, requires a specific server setting to accept remote forwards, needs a firewall rule, and is HTTP by default, so it loses voice input unless you put an SSL-terminating proxy in front of it. A reverse proxy gives full control and a custom domain but needs a server and certificate work. A mesh VPN connects peer to peer and is encrypted, but the phone needs its own client installed.

The reverse proxy sample sets a read timeout of a day

The nginx configuration in the documentation is short, and one line in it is the whole story of what this application does to a connection.

The read timeout is set to 86400 seconds, a full day. Any sane streaming proxy would use a few minutes. A day is the number you write when the upstream connection may legitimately stay silent for hours, which is exactly what a long agent run looks like: minutes of tool calls with no tokens coming back.

The rest is the standard WebSocket recipe. The proxy speaks HTTP version 1.1, forwards the upgrade and connection headers so the WebSocket survives, passes the host header, and proxies to the loopback address of the proxy server. Nothing here is clever, which is the point: the sample is meant to be copied and edited rather than understood.

The certificate paths are placeholders and the server name is a placeholder, which is the only part you must change. The comparison table that follows is the most useful thing in the section, because it lists a genuine drawback for every option including the recommended one, which depends on a third-party service.

Three front ends, three toolchains, one root manifest

The repository layout says this is one application with three faces: a mobile web front end, an Electron desktop application, and an Android directory driven by Capacitor, with a Capacitor configuration file at the root.

The scripts reflect that. There are separate development commands for the server, the web front end, and the desktop shell; a web build; a desktop build that produces packages for three operating systems; and three per-platform desktop build variants so you can build one target without the others. A single install command walks the three sub-projects and installs each in turn.

What the root manifest does not have is as interesting as what it has. It is marked private, so nothing is published to a registry, and it declares exactly one runtime dependency, a plugin that adds progressive web app support. The real dependencies live in the server, web, and desktop sub-projects.

It also does not pin the tools its scripts invoke. The web build calls the bundler through a one-off runner rather than a declared dependency, and the desktop build does the same for the packaging tool and for the shell runtime itself. That keeps the root manifest small, and it means a build resolves those tools at run time, so two machines building the same commit can get different tool versions.

The image builds the front end and drops the toolchain

The container build is two stages on a slim Node base, and it is shaped around what must survive to runtime.

The first stage exists only to build the web front end. It copies the front end's manifest before its source, which is a deliberate ordering: the dependency install is cached against the manifest alone, so editing a component does not invalidate the install layer. Only after the install does the source get copied and built.

The second stage is the runtime, and it is thin. It copies the server's manifest, installs the server's dependencies with development dependencies omitted, copies the server source, and then copies the built front-end output out of the first stage. The bundler, the dev server, and the front end's dependencies never exist in the shipped image. One port is exposed and the server is the entry point.

The compose file adds the piece that makes the container useful: a host gateway mapping, so the proxy inside the container can reach an agent gateway running on the host machine. Without it the container would look for the gateway inside itself, and the default host alias is the convention that makes it work:

bash
docker compose up -d --build

One default deserves a flag. The proxy token in the compose file falls back to a placeholder value if the environment file does not set one, and a placeholder credential is exactly how an open proxy happens.

An installer that pipes a script into your shell

The quick start leads with two one-liners, one per platform, and neither asks you to read anything first.

Each pipes a remote script straight into a shell interpreter, which is the standard convenience and the standard risk. What the script does is documented, which is the part that makes this acceptable: it detects the environment, clones the repository, installs dependencies, builds the front end, and then walks you through configuring the token interactively. It can also register the server to stay resident through a process manager.

One convenience is worth calling out. If the agent platform is already installed on the machine, the script reads the gateway token from its configuration rather than making you copy it from a file. The documentation separately names that file as where the token lives, which is useful for the manual path as well as the scripted one.

The prerequisites are short and honest: the agent gateway must already be running, and you need either a supported Node version or Docker. There is no bundled agent, which is the right boundary for a client and also means the two halves can be versioned independently.

A version 2.0.0 with a two-month gap behind it

Three releases are visible: two in March 2026 and a second major version in May, with the most recent push dated the same day as that tag. Nothing has been tagged since, so the tree has moved past the released version or stopped, and the documentation carries no statement either way.

Two metadata details are worth noting because they disagree with each other. The manifest declares an MIT licence and names a company as the author with a contact address, while the licence field in the repository's own metadata is empty. The manifest is the more specific statement, and it is the one to rely on if the terms matter to you.

The package is private, so there is no published artifact to install from a registry, which is consistent with an application you run from a clone rather than a library others depend on.

The project also points at two siblings: a desktop management panel for the agent platform with a built-in assistant, and a separate full-Chinese translation of the platform's command line and dashboard. Both are referenced from the same organisation, and the second explains the repeated recommendation to use the translated build, which suggests the author's own preference.

Editorial conclusion

ClawApp suits someone whose agent runs on their own machine and who wants to talk to it from a phone without exposing the gateway to a network. It does not suit anyone who needs the voice input on a plain local network, because that feature needs a secure context the local setup cannot provide. Before deploying, set the proxy token yourself rather than accepting the default in the compose file, decide whether to use token or password authentication, and read the tunnel comparison before choosing how the phone reaches the machine.

Frequently asked questions

What problem does ClawApp solve?

The agent platform's gateway listens only on the loopback interface, on a fixed port, so a phone cannot reach it. ClawApp runs a proxy on another port that the phone connects to over a WebSocket, and that proxy performs the device-signing handshake before forwarding to the gateway.

How do I connect ClawApp to the agent gateway?

Set a proxy token of your own along with the gateway token, which is found in the agent's own configuration file. You can instead set a gateway password, which switches to password authentication and takes priority over the token, and which the documentation requires in the hosted tunnelling scenario.

Why does ClawApp need a tunnel for voice input?

Browser speech recognition needs a secure context, so a page served over plain HTTP on a local network cannot use the microphone. The recommended tunnel tool provides HTTPS automatically, while an SSH tunnel is HTTP by default and loses voice input unless an SSL-terminating proxy is placed in front of it.

Which front ends does ClawApp ship?

A mobile web page, a desktop application built with Electron, and an Android package built with Capacitor, plus progressive web app support with offline caching. The desktop build produces packages for three operating systems, with separate scripts for each target.

How do I run ClawApp?

Either with Docker Compose, which reaches a gateway on the host through a host gateway mapping, or directly with a supported Node version using an install script that installs the three sub-projects and builds the web front end. A process manager can keep the server resident and start it at boot.

Official sources

  1. Issues
  2. Project website
  3. qingchencloud/clawapp on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/qingchencloud-clawapp.svg)](https://hysenlabs.com/projects/qingchencloud-clawapp)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/qingchencloud-clawapp.svg)](https://hysenlabs.com/projects/qingchencloud-clawapp)

Was this useful?