Onboarding

unclaw onboard is an interactive setup wizard that prepares your machine to run AI agents through Unclaw. It connects to an Unclaw gateway, discovers your existing API keys, imports them into the gateway, and configures your system so that unclaw run can transparently inject those secrets into agent traffic.

Onboard walkthrough

npm install -g unclaw
unclaw onboard

The wizard walks you through a series of prompts. On a typical run it will:

1. Select a gateway — local or a remote (self-hosted) instance.
2. Start the gateway — on macOS this is a launchd background service; on Linux you choose between a systemd unit or an ephemeral process.
3. Register this machine as a device on the gateway.
4. Install the CA certificate so the gateway can intercept HTTPS traffic.
5. Discover secrets — scans environment variables and config files for known API keys (Anthropic, OpenAI, Gemini, OpenRouter, GitHub, Slack, Grafana, Telegram, Notion, and others). You pick which ones to import.
6. Replace local credentials with placeholders — the originals are backed up, and the files that held them now contain UNCLAW_PLACEHOLDER_* tokens. This way the agent never sees your real keys; they are injected by the gateway at request time.

When the wizard finishes you'll have:

The dashboard is available at http://localhost:8080.

macOS note

On first run macOS will prompt you to approve the Unclaw Network Extension in System Settings → Privacy & Security. The wizard waits for this approval before continuing.

Running agents

Once onboarded, wrap any command with unclaw run:

unclaw run --name openclaw -- openclaw gateway
unclaw run -- node server.js

The gateway intercepts the agent's HTTPS requests, matches them against your configured integrations (by hostname), injects the real API key, forwards the request upstream, and logs it. When the command exits, the session ends.

Options:

• --name NAME — label for this session (defaults to the command name).
• --profile PROFILE — select a specific integration profile instead of the default one.
• --no-expose — (Linux only) don't tunnel the wrapped command's TCP listeners back to the host network. By default Unclaw auto-tunnels them.

If you set up a local gateway but it is not running when you call unclaw run, Unclaw automatically spawns an ephemeral gateway for the lifetime of the command. No manual restart needed.

OpenClaw integration

If OpenClaw is installed on your machine, unclaw onboard detects it and offers to wrap its daemon so that all OpenClaw agent traffic goes through the Unclaw gateway automatically.

Automatic setup

During onboarding, the wizard looks for an existing OpenClaw daemon:

• macOS — checks for a launchd agent at ~/Library/LaunchAgents/ai.openclaw.gateway.plist. If found, it rewrites the plist's ProgramArguments to prepend unclaw --name openclaw -- and updates NODE_EXTRA_CA_CERTS to point to the Unclaw CA bundle. The original plist is backed up with a .bak extension. The daemon is then reloaded automatically.
• Linux — checks for openclaw*.service user systemd units. If found, it writes a systemd drop-in override at ~/.config/systemd/user/<unit>.d/unclaw.conf that prepends unclaw run --name openclaw -- to the unit's ExecStart. The unit is reloaded and restarted automatically.

In both cases the wizard confirms before making changes.

Manual setup

If you installed OpenClaw after onboarding, or prefer to set it up yourself, run the OpenClaw daemon through unclaw run directly:

unclaw run --name openclaw -- openclaw gateway

For a persistent setup, modify the OpenClaw service definition to prepend unclaw run --name openclaw -- to the existing command. For example, in a systemd unit:

ExecStart=/path/to/unclaw run --name openclaw -- /path/to/openclaw gateway

Linux gateway options

On Linux, unclaw onboard asks how you want to run the gateway. The choices are:

Systemd user unit — runs as your user, managed by systemctl --user. Optionally enable linger so the gateway starts at boot and survives logout. Best for single-user machines or personal dev setups.

Systemd system unit — runs as a dedicated unclaw system user, managed by systemctl (requires sudo). Data lives in /var/lib/unclaw/. Best for shared machines or server deployments.

Ephemeral — no persistent service. The gateway is spawned on demand by unclaw onboard or unclaw run and dies when the parent process exits. Good for quick experiments, but concurrent unclaw run invocations share a single gateway that stops when the first one exits. Use a systemd unit if you need concurrent sessions.

You also choose a bind address (loopback, LAN IP, or custom). Loopback is the default and doesn't require authentication beyond the local dev token. A non-loopback bind requires browser-based OAuth sign-in.

Remote gateways

Instead of running a local gateway you can point at a self-hosted Unclaw gateway URL. Remote onboarding skips local gateway setup entirely. You authenticate via an OAuth device-code flow (a browser window opens for sign-in), then the wizard registers your device and discovers secrets as usual.

Managing secrets

After onboarding, open the dashboard at http://localhost:8080 to add, remove, or edit integrations. You can also re-run unclaw onboard to re-discover secrets that were added since the initial setup.

Uninstalling

unclaw offboard

This stops the gateway, removes the Network Extension (macOS) or systemd service (Linux), and optionally deletes all data in ~/.unclaw/.