ClawPilot Link Setup Guide

If you want the ClawPilot app on your phone to connect to the OpenClaw running on your own computer, the easiest path is ClawPilot Link.

You can think of it as a bridge:

• OpenClaw runs on your computer
• ClawPilot runs on your phone
• ClawPilot Link helps both sides find each other

Step 1: Install ClawPilot Link

Open the terminal on the computer where OpenClaw is running, then run:

npm install -g @clawpilot-app/link

After this finishes, your computer will have a new command called clawlink.

Important:

• This step only installs the tool.
• It does not finish pairing yet.

If installation fails because of permissions, first double-check that Node.js and npm were installed correctly on this computer, then try again.

Step 2: Generate the pairing QR code

After installation, run this in the same terminal:

clawlink pair

You should see a QR code in the terminal.

That QR code is what the ClawPilot app on your phone will scan.

If this step succeeds, keep the terminal window open and continue.

Step 3: Scan it from your phone

Open ClawPilot App, then go to:

1. OpenClaw server list
2. Tap Add
3. Choose Scan ClawPilot Link
4. Tap Scan Connect

Then point your phone camera at the QR code shown in the computer terminal.

After the scan succeeds, the app will automatically:

• add this computer as an available OpenClaw server
• save the connection credential
• start trying to connect

In most cases, you do not need to manually type the server address or token.

Step 4: Use it normally after the first pairing

Once the first pairing succeeds, daily use is usually much simpler:

• If Link is already running in the background on your computer, just open ClawPilot App.
• If you rebooted the computer or stopped Link earlier, run clawlink start.

Common commands:

clawlink pair
clawlink start
clawlink status
clawlink doctor
clawlink restart
clawlink stop

How ClawPilot Link chooses the connection path

You can think of it as a three-layer fallback. The app will try the more direct path first:

1. Try direct connection on your local network
2. If that is not available, try direct connection over the public internet
3. If neither works, fall back to Relay automatically

In daily use, these are the two most common situations:

• You are at home, and your phone and the computer running Link are on the same local network. In that case, the app will usually prefer the local network path because it is the most direct one.
• You are away from home, so your phone is no longer on the same network. Then the app will check whether that computer has a usable public entry point. If it does, the app will try to connect directly. If not, or if the connection fails, it will fall back to Relay.

You do not need to switch this manually.

For example, if you were using Relay outside and then come back home, the next reconnect will still try the local network first. If the local path works again, the app will switch back automatically.

If you want to enable public direct connection

Public direct connection is optional. But if you want your phone to rely less on Relay while you are away from home, you need one extra network setup step.

The key part is this:

• your router must forward external port 52378 to port 52378 on the computer running ClawPilot Link

If your home network also has working IPv6, the picture changes a little:

• with IPv4, the most common issue is that you may not have a truly publicly reachable address, so port forwarding is usually the important step
• with IPv6, you often do not hit carrier NAT or CGNAT in the same way, because the device itself may already have a publicly reachable address
• but that still does not guarantee success, because your router, firewall, home network, or current phone network can still block the connection

The simple way to think about it is:

• IPv4 usually means “bring outside traffic into your home network”
• IPv6 usually means “the address may already be reachable, but the whole path still has to allow the connection”

In plain language, you are telling your home router: “If traffic for Link comes from outside, send it to this computer.”

In most cases, you should confirm all of these:

1. ClawPilot Link is running on the computer you want to expose
2. your router forwards 52378 to that computer
3. that computer keeps a stable local network address
4. your router and system firewall are not blocking the connection

If you want to think about IPv4 and IPv6 separately:

• for IPv4, port forwarding is usually the main part
• for IPv6, the more important question is whether your home internet, router, the computer running Link, and your phone’s current network all have usable IPv6
• some routers block inbound IPv6 by default, so you can appear to “have IPv6” and still not get a working public direct connection

If you want to set up IPv4

In most home networks, public direct access over IPv4 usually looks like this:

1. Keep the computer running ClawPilot Link on a stable local network address if possible
2. Open your router admin page and find the section for port forwarding, virtual server, or NAT forwarding
3. Create a rule with:
   • protocol: TCP
   • external port: 52378
   • internal port: 52378
   • internal address: the local IPv4 address of the computer running ClawPilot Link
4. Check the computer’s own firewall and make sure it is not blocking 52378

If you are not sure what that computer’s local IPv4 address is, the easiest way is usually to look at your router’s device list or check the current network details on the computer itself.

If you want to set up IPv6

IPv6 usually does not need the same kind of classic port forwarding that IPv4 does, but you still need to confirm a few things:

1. your home internet and router really have IPv6 enabled
2. the computer running ClawPilot Link has a usable IPv6 address
3. your router is not blocking inbound IPv6 traffic to that computer
4. the computer’s own firewall is not blocking 52378

On many routers, the IPv6 setting is not called port forwarding. It may appear as:

• IPv6 firewall
• inbound rules
• allow external access
• allow incoming traffic to a LAN device

If your router has options like these, you usually need to allow inbound 52378/TCP to the computer running ClawPilot Link.

The simple way to think about it is:

• with IPv4, you usually forward the port inward
• with IPv6, you usually allow inbound traffic that would otherwise be blocked

But there is one important thing to understand:

• port forwarding does not guarantee that public direct connection will work
• some home internet connections do not actually have a publicly reachable IPv4 address
• some networks are behind carrier NAT, CGNAT, upstream routers, or firewalls
• some setups appear to have IPv6, but the phone network, home network, or router still does not allow a real end-to-end connection
• some setups allow IPv4 port forwarding but still block inbound IPv6
• your phone’s current network may only have IPv4, or its IPv6 path may be unstable, so direct connection can still fail

So the most accurate way to think about it is:

• port forwarding is one requirement for public direct connection
• but it is not a guarantee

If you do not want to deal with public network setup, that is completely fine.

As long as Link and Relay are working, ClawPilot can still reach your OpenClaw. Public direct connection is only a “use it when available” path, not something you must configure for Link to work.

The most useful daily commands

clawlink start

Use this when the computer has already been paired, but the background service is not currently running.

Typical cases:

• the computer just rebooted
• you stopped Link manually earlier
• you want to bring the background service back

clawlink status

This is the best first status command to check.

It tells you:

• which Link version is installed
• whether the background service is running
• whether OpenClaw was found
• how the app is likely to connect right now

If your first question is “is this actually connected?”, start here.

clawlink doctor

Use this when something feels wrong but you do not know where the problem is.

It runs a fuller health check and gives clearer fix suggestions.

Update Link

If you want the latest version, run:

npm install -g @clawpilot-app/link@latest
clawlink restart

The first command updates the package. The second restarts the background service so it uses the new version.

Troubleshooting order

If your phone still cannot connect, do not start by reinstalling everything. This order is usually faster:

1. Run clawlink status
2. If that is still unclear, run clawlink doctor
3. Confirm OpenClaw itself works on this computer
4. If you updated Link recently, run clawlink restart
5. If the QR code expired, run clawlink pair again and rescan

Short version

For first-time setup, most people only need to remember these two commands:

npm install -g @clawpilot-app/link
clawlink pair

Install it, generate the QR code, scan it, and you are usually done.

Checked on 2026-04-12.