OpenClaw Guide
OpenClaw and ngrok: Exposing a Local Agent Safely
Sooner or later a locally running agent needs a public URL — usually because an integration wants to send it a webhook. ngrok is the standard answer, and for development it is a good one. It is worth understanding what a tunnel opens up, what the free tier will and will not do, and when the tunnel is solving a problem you could simply not have.
Why the question comes up
Most of what an agent does is outbound: it calls a model, fetches a page, hits an API. Outbound traffic works fine from a laptop. The trouble starts with anything inbound — a service that wants to notify your agent when something happens, an OAuth provider that needs to redirect back to a real URL, a platform that delivers events by webhook.
Those all need an address on the public internet, and a local port is not one. A tunnel bridges that gap: ngrok runs an agent process on your machine that maintains an outbound connection to ngrok's servers, and traffic arriving at your public ngrok URL is forwarded down that connection to your local port.
The basic shape
The OpenClaw gateway listens on port 18789 by default — that single port serves the control UI, WebSocket connections, and channel ingress for platform webhooks. So the tunnel points there:
ngrok http 18789If you changed the gateway port in your configuration, substitute your own. Tunnelling the wrong port is the most common first mistake here, and it presents as a confusing 502 rather than an obvious error.
ngrok prints a public URL that forwards to your local port. Point the webhook at that URL and callbacks start arriving. The request inspector, available on every tier, lets you look at the traffic and replay it — which is genuinely the best part of the tool for debugging, since you can re-fire a webhook without asking the sending service to do it again.
Lock it down before you use it for anything real
This is the part that gets skipped. A tunnel does not just let your webhook provider in — it lets in anyone who has the URL. Pointing one at an agent is a bigger exposure than pointing it at a static site, because the agent holds credentials, can call tools, and can act on instructions it receives.
- Restrict at the tunnel level. Basic authentication or an IP allowlist limited to the sending service's published egress ranges keeps casual traffic out entirely.
- Verify webhook signatures in the agent. Most providers sign their payloads; treat an unsigned or badly signed request as hostile rather than merely odd.
- Never run agent traffic over unencrypted HTTP anywhere real data is involved.
- Do not leave a tunnel open after you stop using it. An unattended tunnel to a machine holding your keys is a standing invitation.
- Treat the URL as a secret. Random subdomains are obscurity, not access control.
Worth stating plainly: a webhook endpoint is untrusted input arriving at something that can take actions. Signature verification is not optional hardening — it is the boundary.
What the free tier actually gives you
Worth checking the current limits rather than trusting older write-ups, which are widely out of date on this. The free plan allows up to three online endpoints, includes roughly 1 GB of data transfer per month, and assigns your account one persistent development domain — something along the lines of your-assigned-name.ngrok-free.app. Request inspection and replay are included.
The persistent domain matters more than it sounds: because the address is tied to your account rather than generated per session, a webhook registered against it keeps working across restarts. The older complaint about re-registering a webhook every time the tunnel drops no longer applies on the free plan.
What remains is the data-transfer ceiling and the fact that the tunnel only exists while the ngrok process is running on your machine. Neither is a problem for development; both matter if you were planning to depend on it.
When you do not need a tunnel at all
Step back and the tunnel is a workaround for one specific constraint: the agent lives on a machine with no stable public address. That constraint is not a law of nature.
A hosted instance already has a public endpoint. Webhooks point straight at it, the address does not change when the process restarts, TLS is handled, and there is no second piece of software whose failure takes the integration down. If you were reaching for a tunnel purely so a callback could find your laptop, moving the agent somewhere reachable removes the problem rather than routing around it.
The same applies to chat channels. Pairing an agent to a channel through a hosted gateway does not require exposing your own machine at all.
So which should you use
- Use ngrok while developing locally, when you need to inspect and replay webhook traffic, or for a short-lived test against a real provider.
- Use a real public endpoint — a VPS with a domain, or a managed instance — the moment the integration is something you rely on. A tunnel is a development tool, not an uptime strategy.
If you stay self-hosted, the VPS guide covers giving an agent a stable address of its own; the tmux guide covers the related trap of keeping a local process alive.
OpenClaw and ngrok FAQ
Why would an AI agent need ngrok at all?
Because some integrations push data to you rather than being polled. A webhook needs a public URL it can reach, and an agent running on your laptop does not have one. ngrok creates a tunnel that gives localhost a public address so those callbacks can arrive.
Is it safe to expose an agent through a tunnel?
Only if you restrict it. A tunnel makes your local service reachable by anyone who learns the URL, and an agent is a high-value target because it holds credentials and can take actions. Put authentication or IP restrictions at the tunnel level, and never carry agent traffic over plain HTTP where real data is involved.
What are ngrok’s free-tier limits?
The free plan allows up to three online endpoints, includes about 1 GB of data transfer per month, and gives your account one persistent development domain rather than a URL that changes between runs. Request inspection and replay are included. Because the domain is stable, a webhook registered against it survives restarts.
Do I need ngrok with a hosted agent?
No. A hosted instance already has a stable public address, so webhooks can be pointed straight at it. The tunnel exists to work around an agent living on a machine without one — remove that constraint and the whole layer disappears.