haitham/horus-3d
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e24ed4153297d4745f085e5c298426965eb58ca7
horus-3d/TUTORIAL.md
T
Luke The Dev 4fa4f13558 First Release of Claw3D (#11) 
Co-authored-by: iamlukethedev <iamlukethedev@users.noreply.github.com>
2026-03-19 23:14:04 -05:00

7.4 KiB
Raw Blame History

Claw3D + OpenClaw + Tailscale Setup Tutorial

This guide is a step-by-step runbook for the most common production-like setup:

  • Machine A runs OpenClaw Gateway.
  • Machine B runs Claw3D.
  • Tailscale connects both machines securely.

If you follow this exactly, people should avoid the most common confusion: Claw3D does not install or run OpenClaw for you.

0) Architecture and Responsibilities

  • OpenClaw is the runtime and Gateway.
  • Claw3D is the UI and Studio proxy.
  • Claw3D connects to an already running OpenClaw Gateway.
  • In this tutorial, the Gateway lives on a different machine from Claw3D.

1) Prerequisites

Machine A (Gateway host)

  • macOS, Linux, or WSL2.
  • Internet access.
  • Ability to install OpenClaw and Tailscale.

Machine B (Claw3D host)

  • Node.js 20+ recommended for this repo.
  • npm 10+ recommended.
  • Internet access.
  • Ability to install Tailscale.

Accounts and permissions

  • A Tailscale account for your tailnet.
  • If your tailnet uses device approval, you need Owner/Admin/IT admin access in Tailscale admin.

2) Install and Start OpenClaw on Machine A

OpenClaw official install docs are here: Install and Getting Started.

2.1 Install OpenClaw

On Machine A:

curl -fsSL https://openclaw.ai/install.sh | bash

2.2 Run onboarding and install daemon

openclaw onboard --install-daemon

2.3 Verify Gateway health

openclaw gateway status
openclaw status

You want a healthy result such as runtime running and RPC probe ok.

2.4 Get your Gateway token

You will need this token in Claw3D:

openclaw config get gateway.auth.token

Store it securely.

3) Install and Authorize Tailscale on Both Machines

Tailscale docs: Serve overview, Serve CLI, and Device approval.

3.1 Install Tailscale

Install Tailscale on Machine A and Machine B using official installers: Tailscale downloads.

3.2 Join both machines to the same tailnet

On each machine:

tailscale up
tailscale status

Confirm both machines appear in the same tailnet.

3.3 If your tailnet requires approval, approve devices

In Tailscale admin:

  1. Open Machines.
  2. Find devices marked Needs approval.
  3. Approve both Machine A and Machine B.

Without this, the machines cannot communicate over tailnet traffic.

4) Expose OpenClaw Gateway Through Tailscale on Machine A

You have two valid ways. Pick one.

Option A (simple and explicit): Tailscale Serve command

On Machine A, keep Gateway bound locally (127.0.0.1:18789) and publish through Serve:

tailscale serve --yes --bg --https=443 http://127.0.0.1:18789
tailscale serve status

Notes:

  • Newer Tailscale CLI uses --https=443.
  • If you are on older docs/commands, you may see syntax like --https 443. Use tailscale serve --help on your installed version.

Option B (OpenClaw-managed Tailscale mode)

OpenClaw can manage Tailscale mode itself:

openclaw gateway --tailscale serve

OpenClaw Tailscale docs: Gateway Tailscale.

4.1 Confirm the public tailnet URL

You need the https://<gateway-host>.<tailnet>.ts.net host.

This host is what Claw3D will use as wss://<gateway-host>.<tailnet>.ts.net.

5) Install and Run Claw3D on Machine B

On Machine B:

git clone https://github.com/iamlukethedev/Claw3D.git claw3d
cd claw3d
npm install
cp .env.example .env
npm run dev

Then open:

  • http://localhost:3000

6) Connect Claw3D to OpenClaw

In Claw3D connection UI:

  1. Set Gateway URL to:
    • wss://<gateway-host>.<tailnet>.ts.net
  2. Paste the token from Machine A (openclaw config get gateway.auth.token).
  3. Click Connect.

Important:

  • Use wss:// for Tailscale HTTPS endpoints.
  • Use ws://localhost:18789 only when Gateway is local to the same machine as Claw3D or when using an SSH tunnel.

7) Required Device-Pairing Approval Step

This is the step people often miss.

After Claw3D is running and tries to connect for the first time, approve pending device pairing on Machine A:

openclaw devices list
openclaw devices approve --latest

OpenClaw devices docs: openclaw devices.

If multiple requests are pending, approve by id instead:

openclaw devices approve <requestId>

8) Verification Checklist

Run this checklist in order:

  1. openclaw gateway status on Machine A shows healthy runtime.
  2. tailscale status on both machines shows connected devices in same tailnet.
  3. tailscale serve status on Machine A shows active Serve config for port 443 to 127.0.0.1:18789.
  4. Claw3D connect UI uses wss://...ts.net plus valid token.
  5. openclaw devices approve --latest has been run after first connect attempt.
  6. Claw3D UI shows gateway connected and loads agents.

9) Troubleshooting

EPROTO or wrong version number

  • Usually means protocol mismatch.
  • Fix: if your endpoint is HTTPS/Tailscale Serve, use wss://....
  • Do not use wss:// against a plain ws:// endpoint.

401 or auth errors from Claw3D

  • Re-copy token from Machine A:
    • openclaw config get gateway.auth.token.
  • Confirm Gateway auth mode and token are current.

Claw3D still cannot connect after token is correct

  • Approve pending device:
    • openclaw devices approve --latest.
  • Check pending requests:
    • openclaw devices list.

Tailscale URL works nowhere

  • Confirm both devices are approved in Tailscale admin if device approval is enabled.
  • Re-run:
    • tailscale status.
    • tailscale serve status.
  • Recreate serve config if needed:
    • tailscale serve reset.
    • tailscale serve --yes --bg --https=443 http://127.0.0.1:18789.

Gateway itself is unhealthy

  • Run:
    • openclaw doctor.
    • openclaw gateway restart.
    • openclaw gateway status.

10) Security Notes

  • Keep Gateway bound to loopback unless you have a deliberate reason not to.
  • Do not commit tokens into git or .env files intended for sharing.
  • Prefer Tailscale Serve over exposing raw Gateway ports publicly.
  • Treat OpenClaw device pairing approval as a security gate, not a one-time annoyance.

References

Reference in New Issue View Git Blame Copy Permalink