OpenClaw Field Guide

Section 20: Terminal Basics and Command Cheat Sheet

You can use OpenClaw mostly through chat and dashboard. But when something needs setup, restart, or repair, the terminal becomes your control panel.

Good news: for non-technical users, you only need a small command set.

This section gives you exactly that.

What the terminal is (plain English)

The terminal is a text-based app where you run commands directly on your computer or server. Think of it as a precise remote control:

  • fast
  • explicit
  • great for diagnostics and recovery

You do not need to memorize everything. Keep this section bookmarked and copy/paste commands carefully.

::: beginner Terminal skill is not about typing fast. It is about running the right command, reading output calmly, and making one change at a time. :::

How to open the terminal

  • macOS: open the Terminal app (Applications → Utilities → Terminal)
  • Linux: open your distro's terminal app (often preinstalled)
  • Windows: use PowerShell or Windows Terminal; if needed for compatibility, use WSL2 for Linux-like behavior

If you run OpenClaw on a VPS, you'll usually connect by SSH first, then use the same commands.

Use these to know where you are and move around safely:

🖥️ Type this in your terminal:

pwd

Shows your current folder path ("Where am I?")

🖥️ Type this in your terminal:

ls

Lists files/folders in the current location ("What's here?")

🖥️ Type this in your terminal:

cd foldername

Moves into a folder ("Go there")

🖥️ Type this in your terminal:

cd ..

Moves up one folder ("Go back one level")

::: tip If you feel lost, run pwd and ls. Those two commands solve most navigation confusion. :::

OpenClaw core command set (the ones you'll actually use)

Check if OpenClaw is healthy

🖥️ Type this in your terminal:

openclaw status

Use this first when troubleshooting.

Start gateway

🖥️ Type this in your terminal:

openclaw gateway start

Use when OpenClaw is stopped.

Stop gateway

🖥️ Type this in your terminal:

openclaw gateway stop

Use to halt activity (for maintenance, loops, or safe config work).

Restart gateway

🖥️ Type this in your terminal:

openclaw gateway restart

Use after updates or config changes.

Open dashboard

🖥️ Type this in your terminal:

openclaw dashboard

Use to view service/channel state in the web UI.

Update OpenClaw

🖥️ Type this in your terminal:

openclaw update

Use to pull latest version.

Run diagnostics

🖥️ Type this in your terminal:

openclaw doctor

Use for one-command checks across common failure points.

Re-run setup wizard

🖥️ Type this in your terminal:

openclaw onboard

Use when initial setup was incomplete, auth expired, or channel pairing broke.

Log reading (your best troubleshooting friend)

Stream logs live

🖥️ Type this in your terminal:

openclaw logs

Good for watching real-time behavior while reproducing an issue.

View recent log tail

🖥️ Type this in your terminal:

openclaw logs --limit 50

Good for quick diagnosis without scrolling huge output.

::: warning Logs may include sensitive context (usernames, service details, partial tokens/errors). Share logs carefully and redact when posting publicly. :::

Config file safety commands

Before major edits or upgrades, backup config:

🖥️ Type this in your terminal:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

View current config content:

🖥️ Type this in your terminal:

cat ~/.openclaw/openclaw.json

Quick cheat sheet (copy/paste block)

🖥️ Type this in your terminal:

openclaw status
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw dashboard
openclaw update
openclaw doctor
openclaw onboard
openclaw logs
openclaw logs --limit 50
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
cat ~/.openclaw/openclaw.json

Command habits that prevent mistakes

  1. Run one command at a time

    • Wait for output
    • Read before continuing

  2. Copy exactly

    • Small typos create confusing errors

  3. Prefer restart over random edits

    • Many issues clear with clean restart + doctor

  4. Keep a known-good path

    • Backup config before risky changes

  5. Write down what worked

    • Build your own mini runbook for recurring issues

::: power-user Create a personal "first response sequence" note: status → logs tail → doctor → restart → retest. Consistency improves recovery speed. :::

Realistic scenario: "I'm on Windows, command says not found."

You open PowerShell and try openclaw status, but it returns a command-not-found error.

Likely causes:

  • OpenClaw not installed in current environment
  • PATH not refreshed after install
  • You're in a shell/session that does not see global npm binaries

Recovery approach:

  1. Close and reopen terminal
  2. Retry status command

🖥️ Type this in your terminal:

openclaw status
  1. If still failing, run setup flow again in the correct environment

🖥️ Type this in your terminal:

openclaw onboard
  1. Once available, verify health and diagnostics

🖥️ Type this in your terminal:

openclaw doctor

Outcome: command access restored, setup verified, you can continue normally.

::: action Save this section as your personal terminal playbook. You don't need 200 commands-just these core ones used consistently. :::