Skip to main content

​
Quickstart

Get SimpleClaw installed and send your first message in under 5 minutes.

​
Prerequisites

  • Node.js: Version 22 or higher
  • Package Manager: npm, pnpm, or bun
  • Operating System: macOS, Linux, or Windows (WSL2)
Check your Node version with node --version. If you need to upgrade, visit nodejs.org.

​
Installation

Install SimpleClaw globally via npm: 
npm install -g simpleclaw@latest

​
Setup

Run the onboarding wizard to configure SimpleClaw: 
simpleclaw onboard --install-daemon
1

Gateway Configuration

The wizard will configure the WebSocket gateway to run on port 18789.
2

Model Setup

You’ll be prompted to configure your LLM provider (Anthropic, OpenAI, etc.) and API keys.
3

Daemon Installation

The --install-daemon flag installs a system service (launchd on macOS, systemd on Linux) to keep the gateway running.
The wizard creates configuration at ~/.simpleclaw/config.yaml and sets up your workspace.

​
Verify Installation

Check that the gateway is running: 
simpleclaw gateway status
You should see output indicating the gateway is running on port 18789.

​
Open the Control UI

Launch the web dashboard: 
simpleclaw dashboard
This opens http://127.0.0.1:18789/ in your browser, where you can:
  • Chat with your assistant
  • View active sessions
  • Monitor channel status
  • Manage configuration
If the Control UI loads, your SimpleClaw installation is working!

​
Send Your First Message

​
Option 1: CLI Agent

Send a message directly from the command line: 
simpleclaw agent --message "Hello, SimpleClaw!" --thinking high
The --thinking high flag shows the agent’s reasoning process.

​
Option 2: WebChat

Use the WebChat interface in the Control UI:
  1. Open http://127.0.0.1:18789/
  2. Navigate to the WebChat tab
  3. Type your message and press Enter

​
Option 3: Channel Message

If you’ve configured a channel (WhatsApp, Telegram, etc.): 
simpleclaw message send --target +1234567890 --message "Hello from SimpleClaw"
Replace +1234567890 with your phone number or channel ID.

​
Understanding Responses

The agent will respond with:
  • Message content: The assistant’s response
  • Thinking process: Internal reasoning (with --thinking high)
  • Tool calls: Any tools used (browser, canvas, etc.)
  • Session info: Session ID and context
Example output: 
[Agent: main]
[Session: main:telegram:123456789]
[Model: anthropic-claude]

> Hello! I'm SimpleClaw, your personal AI assistant. How can I help you today?

[Tokens: 45 input, 23 output]

​
Next Steps

Now that SimpleClaw is running, explore these features:

Add Channels

Connect WhatsApp, Telegram, Discord, and more

Configure Models

Set up multiple LLM providers and failover

Voice Setup

Enable Voice Wake and Talk Mode

Multi-agent Routing

Create specialized agents for different tasks

Security Setup

Configure DM pairing and allowlists

Troubleshooting

Common issues and solutions

​
Common Commands

Here are some useful commands to get started: 
# Check gateway status
simpleclaw gateway status

# Send a message via the agent
simpleclaw agent --message "Summarize my day" --thinking high

# View channel status
simpleclaw channels status

# Open the dashboard
simpleclaw dashboard

# Run diagnostics
simpleclaw doctor

# View configuration
simpleclaw config get

​
Troubleshooting

​
Gateway not starting

Run the diagnostic tool: 
simpleclaw doctor
This checks for configuration issues, permissions, and port conflicts.

​
No response from agent

Verify your model configuration: 
simpleclaw config get models
Ensure your API keys are set correctly.

​
Command not found

Make sure SimpleClaw is in your PATH: 
which simpleclaw
If not found, reinstall or add ~/.npm-global/bin to your PATH.

​
Learn More

Installation Guide

Detailed installation instructions for all platforms

Configuration

Complete configuration reference

CLI Reference

Full command-line documentation

First Chat Guide

Detailed guide to your first conversation

Build docs developers (and LLMs) love

Get started for freeTalk to us