Your first OpenClaw setup

Tutorial · OpenClaw · 25 min

Install and run OpenClaw

Set up your own AI agent, connect a provider, and get your first reply. A practical guide from installation to a working chat.

Start tutorial
OpenClaw lobster logo with the words Install. Connect. Run.
Paulo Cauhi ·

From an empty terminal to your first reply

You’ll install OpenClaw, connect an AI provider, and send a message from its browser dashboard. Start on your own computer. Once that works, the optional server section explains how to keep it running elsewhere.

01Install Put OpenClaw on your computer.02Connect Choose the AI that answers you.03Run Open the dashboard. Get a reply.

Before you start

  • A Mac, Windows PC, or Linux computer with an internet connection.
  • Access to an AI provider. Onboarding can detect supported existing logins or ask you to connect a provider. API usage may be billed separately.
  • A terminal window and time to complete sign-in. No messaging app is needed for this lesson.

Running locally doesn’t mean the AI is offline. OpenClaw runs on your machine; when you choose a cloud model, requests are sent to that provider. Your computer also needs to stay awake while the agent is running.

Install for your operating system

Open Terminal on macOS, or your terminal app on Linux. Paste this command and press Return.

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

This downloads and runs the official installer. It installs OpenClaw, checks Node.js, and starts onboarding. Installer reference.

The installer should take you into onboarding. If it finishes without opening setup, start it yourself:

Terminal
openclaw onboard

Connect your AI provider

Choose Custom setup so you can review the connection and access options. Select a detected connection or follow the sign-in instructions for your chosen provider. Enter credentials only in the provider’s sign-in flow or the local setup prompt.

Let the connection check finish. If it fails, fix the reported authentication or account issue before continuing. Don’t treat an installed CLI as proof that the AI connection works.

Review the access settings deliberately: Quick start currently uses full access. Permissions depend on the access mode, tools, and integrations you enable. Keep the initial setup small and read the onboarding reference and tool security guidance before giving the agent more access.

Open the dashboard and get a reply

Onboarding can open the dashboard for you. To open it again, run this in a second terminal while the Gateway is still running. The Gateway is the process that connects the dashboard to your agent.

Terminal
openclaw dashboard

Use the address this command provides. The default local address is http://127.0.0.1:18789, but the generated link handles your configured connection. Treat any token in that link as a password.

In chat, send a simple message such as “Reply with one sentence confirming you can read this message.” You’re looking for an actual AI reply. A page loading successfully is only the first check.

If the browser cannot connect, check the service:

Terminal
openclaw gateway status

See the dashboard guide for authentication and connection details.

Keep it running in the background

If onboarding left the Gateway running in your terminal, pressing Ctrl+C stops it without erasing your configuration. Stop that foreground process, then install the background service:

Terminal
openclaw gateway install
openclaw gateway status

Confirm that the status reports a running Gateway, then reopen the dashboard and try another message. A background service keeps the terminal out of the way; it cannot keep a sleeping laptop online. The getting-started guide explains the service used on each platform.

Optional: run it on a Linux server

Use a server when you need OpenClaw available while your laptop is off. You’ll need a Linux server you can access over SSH, a regular user account, and a plan for hosting costs. If you don’t have one yet, start with the official Linux server guide.

Connect to the server, then follow the Linux install, onboarding, and service steps above inside that SSH session. Provider credentials on your laptop are not automatically available on the server.

Keep the Gateway bound to loopback with authentication enabled. From a terminal on your laptop, open a tunnel, replacing user and your-server with your SSH details:

Terminal · on your laptop
ssh -N -L 18789:127.0.0.1:18789 user@your-server

Leave that terminal open. Visit http://127.0.0.1:18789 on your laptop and authenticate with the server’s Gateway credentials. If a local OpenClaw instance already uses that port, use a different local port as described in the remote access guide. You do not need to open port 18789 to the public internet.

Stuck? Start with the symptom

  • “Command not found”: reopen your terminal after installation and try openclaw --version. If it still fails, check the installer’s final output.
  • Dashboard won’t connect: run openclaw gateway status. Check that you are opening the address for the machine where the Gateway is running.
  • Dashboard opens, but chat fails: check your provider authentication, model availability, and account limits. Revisit the connection with openclaw onboard.

For a broader diagnosis, run the command below and read its findings before applying changes. More detail is in the troubleshooting guide.

Terminal
openclaw doctor

Done means: the Gateway is running, the dashboard connects, and you have received an AI reply. You’re then ready to connect a messaging channel in the next lesson.

Mark as complete

Install and run OpenClaw

Next Module: Connect your first channel

Engagement is unavailable right now. The article remains available.

Comments

Comments

Engagement is unavailable right now. The article remains available.

Comment privacyCommenting guidelines