Common Tasks#

OpenClaw helps you run an AI assistant that connects to your messaging apps and devices. The CLI gives you direct control over setup, connections, and daily use. Below are the most common things people do after installing.

How do I set up OpenClaw for the first time?#

The onboard process walks you through the basics in order.

1. Open a terminal and run the onboard command.
2. Answer the prompts about your workspace location, gateway settings, and which channels you want to connect.
3. When the process reaches the channels step, follow the instructions for any messaging services you use.
4. Add any skills or tools that match how you plan to use the assistant.
5. If you want OpenClaw to start automatically in the background, include the install-daemon option when you run the command.

The process works on macOS, Linux, and Windows. On Windows and mobile platforms you will also need the companion apps for full device features. After onboarding finishes, you can check everything with the doctor command.

See the Getting Started guide for a broader orientation.

How do I start and stop the Gateway?#

The Gateway is the part that keeps your connections and agent running.

1. Check the current state with the gateway status command.
2. Start the Gateway by running the gateway command. Add the verbose flag if you want to see more detail while it starts.
3. To run on a specific port or network interface, add the port or bind options.
4. Stop the Gateway with the gateway stop command when you need to shut it down cleanly.

If you chose the daemon option during onboarding, the Gateway will usually start on its own after a restart. You can still use the status and stop commands to manage it.

How do I connect a companion node?#

Companion nodes let your phone, tablet, or computer provide extra capabilities such as voice, camera, screen sharing, or location.

1. Install the companion app on the device you want to connect.
2. Open the app and begin the connection process to your Gateway.
3. On your main computer, run the nodes command to see the list of available or pending devices.
4. Approve the new node through the CLI or through the Control UI if the app shows a pairing request.
5. Once approved, the node will appear in the list and its features will become available to your agent.

You can rename nodes or remove them later with the same nodes command. Non-local connections always require explicit approval for security.

How do I connect a messaging channel?#

OpenClaw supports WhatsApp, Telegram, Discord, Slack, and similar services through channel plugins.

1. Run the plugins install command with the name of the channel you want to add, if it is not already present.
2. Use the onboard command again or the config commands if you need to enter account details.
3. Start or restart the Gateway so the new channel can connect.
4. For new contacts, the default behavior asks for pairing approval before the assistant will respond.

Once the channel is active, messages from approved contacts flow into sessions that your agent can read and reply to.

How do I approve a new contact or device?#

By default, unknown senders in direct messages must be approved before the agent processes their messages.

1. When an unapproved person sends a message, OpenClaw will reply with a short code.
2. Copy the code.
3. Run the pairing approve command, giving the channel name and the code.
4. The contact is now approved and future messages will reach the agent.

You can also approve pairings for companion nodes the same way. If you prefer a more open setup, you can change the policy for a channel, but the doctor command will warn you about less secure choices.

How do I talk to the agent or send a test message?#

You can interact directly from the terminal or through your connected channels.

1. To send a quick test message to a specific contact or group, use the message send command and provide the target and the text.
2. To speak with the agent itself, use the agent command followed by your message.
3. The agent will process the request, use any available tools or skills, and return a response.

Responses also appear in your connected messaging apps once channels are set up. You can continue the conversation in the app or from the terminal.

How do I install plugins or fix problems?#

Plugins add new tools, channels, or skills.

1. Run the plugins install command with the plugin name or package you want.
2. Use the plugins inspect command afterward to see what the plugin provides and whether it loaded correctly.

If something feels off, run the doctor command. It checks for common issues such as misconfigured DM policies, port conflicts, or invalid settings.

1. Run the doctor command by itself to see a report.
2. Add the fix option to let it repair problems it can handle automatically.
3. Add the yes option if you want it to proceed without asking for confirmation each time.

After fixes, restart the Gateway and test the affected area. For more help with specific errors, see the troubleshooting page or the FAQ.