‍‌​

1. Pre-installation Preparation

• System and Hardware Requirements

• Installing Node.js

• Installing Docker Desktop (Optional)

2. Using the Official Installation Script (Recommended)

• Running the Installation Script on macOS

• Running the Installation Script on Linux

• Running the Installation Script on Windows

• Completing Initial Configuration

• Verifying Installation and Operation

3. Global Installation via npm

• Installing the Clawdbot CLI Tool

• Verifying the Installation

• Running the onboarding Wizard

• Manually Starting the gateway

4. Installing from Source Code (For Developers)

• ObtAIning the Source Code

• Installing Dependencies

• Building the Project

• Running ClawDBot

5. Containerized deployment with Docker (Optional)

• Pulling the ClawdBot Image

• Running the ClawDBot Container

• Configuring Inside the Container

• Persisting Configuration and Data

6. Common Issues and Solutions

• Issue: Node.js version too low during installation

• Issue: Permission errors during installation

• Issue: “command not found” when running clawdbot

• Issue: Port conflicts or inaccessible dashboard on macOS

• Issue: Compatibility problems or limited functionality on Windows

• Issue: Docker container fails to start or operate correctly

7. Best Practices and Learning Path

• Understanding Core Concepts

• Planning automation Scenarios

• Gradually Expanding Your Skills

• Ensuring Data Security

• Continuous Learning and Updates

1. Pre-Installation Preparation

System and Hardware Requirements

Before installing ClawDBot, ensure your device meets the following minimum requirements:

• Operating System:

• macOS: macOS 11 Big Sur or later. Docker Desktop officially supports the current and previous two major macOS versions, so macOS 12 Monterey and macOS 13 Ventura are fully compatible. Note that macOS 10.15 Catalina and earlier are no longer supported. If your Mac mini runs an older version, consider upgrading for compatibility.

• Processor Architecture:
  ClawDBot runs on both Intel-based and Apple Silicon (M1/M2, etc.) Mac minis. This guide applies regardless of your chip type. However, when downloading software like Node.js, choose the version matching your architecture.

• Memory (RAM):
  Minimum 4GB RAM; 8GB or more recommended for smoother performance. While ClawDBot itself has modest memory usage, complex tasks or multitasking benefit from additional RAM.

• Storage Space:
  At least 500MB of free disk space for ClawDBot and its dependencies. Allocate more if you plan to store extensive chat history or files.

• Network Connection:
  A stable internet connection is required to download dependencies during installation and to communicate with external services (e.g., AI model APIs, messaging platforms).

• Administrator Privileges:
  Administrator access is needed to install software and execute commands. Ensure you have admin credentials for your Mac mini to enter passwords when prompted.

Installing Node.js

ClawDBot is built on Node.js, so you must install the Node.js runtime before proceeding. Follow these steps:

1. Download Node.js:
   Visit nodejs.org and download the latest Long-Term Support (LTS) version for macOS. Choose the installer (.pkg) matching your chip architecture. ClawDBot requires Node.js v22 or higher—verify the version meets this requirement.

2. Install Node.js:
   Double-click the downloaded .pkg file and follow the installation wizard. By default, Node.js and npm (Node Package Manager) are installed to /usr/local/bin and added to your system PATH.

3. Verify Installation:
   Open Terminal and run:

   node -v
   npm -v

   If both commands return version numbers, the installation succeeded.

Note: Node.js is required for non-Docker deployments (e.g., official script or npm installation). Ensure you’re using Node.js v22+, as older versions may cause ClawDBot to malfunction.

2. Using the Official Installation Script (Recommended)

ClawDBot provides an official installation script that automates dependency setup, CLI installation, and initial configuration. This is the simplest and most reliable method.

On macOS

1. Run the Installation Script:
   Open Terminal and execute:

   curl -fsSL https://clawd.bot/install.sh | bash

   The script downloads and runs automatically. You may be prompted for your admin password.

2. Wait for Completion:
   The script will:

• Detect your OS and architecture

• Install Node.js (if missing)

• Install the clawdbot CLI tool

• Add clawdbot to your system PATH
  This process takes a few minutes.

3. Verify Installation:
   After completion, run:

   clawdbot --version

   If a version number appears, installation was successful.

On Linux

Run the Same command in your Linux terminal:

curl -fsSL https://clawd.bot/install.sh | bash

The script auto-detects your Linux distribution, installs dependencies, and sets up ClawDBot. Verify with clawdbot --version.

On Windows

Windows is not natively supported. Use WSL2 (Windows Subsystem for Linux 2) instead:

1. Install WSL2:
   In PowerShell (as Administrator), run:

   wsl --install -d Ubuntu

   Reboot your PC to complete setup.

2. Run the Script in WSL2:
   Launch your WSL2 Ubuntu terminal and execute:

   curl -fsSL https://clawd.bot/install.sh | bash

3. Verify Installation:
   In the WSL2 terminal, run clawdbot --version.

Why WSL2? Native Windows support is limited/unstable. WSL2 provides a full Linux environment for reliable operation.

Completing Initial Configuration

After installation, run the interactive onboarding wizard:

clawdbot onboard

The wizard guides you through:

• Gateway Mode: Select Local (runs on your machine).

• AI Model Authentication:

• Recommended: anthropic API Key (enter a valid key when prompted).

• Alternative: OpenAI, OLlama, or other providers.

• Default Model: Choose a model (e.g., Anthropic/claude-Opus-4-5 for best performance).

• messaging channels: Enable platforms like WhatsApp, Telegram, or Discord. Provide required credentials (e.g., phone number for WhatsApp, bot tokens for Telegram/Discord).

• Background Service:

• macOS: Installs a launchd service (auto-starts at boot).

• Linux: Installs a systemd service.
  Select "Yes" for automatic startup.

Verifying Installation and Operation

• Check Service Status:  

  clawdbot status  # Shows "Running" if active

• Access Web Dashboard:
  Open http://127.0.0.1:18789 in your browser. A login page confirms successful operation.

• Test Messaging:
  Send a message via a configured channel (e.g., Telegram). A reply verifies end-to-end functionality.

Troubleshooting: Issues with WhatsApp QR codes or Discord tokens usually stem from third-party platform setup—not ClawDBot itself. Consult official docs for fixes.

3. Global Installation via npm

Use this method if you prefer manual control or the official script fails.

Installing the CLI Tool

1. Global Install:

   npm install -g clawdbot@latest

   Or with pnpm:

   pnpm add -g clawdbot@latest

2. Verify Installation:

   clawdbot --version

Running the Onboarding Wizard

Complete initial setup identically to the script method:

clawdbot onboard

Manually Starting the Gateway

The npm install does not auto-start the gateway. Launch it manually:

clawdbot gateway

• Run in Background (macOS/Linux):

  nohup clawdbot gateway &

• Auto-Start Setup:
  Configure launchd (macOS) or systemd (Linux) for boot-time startup. Refer to ClawDBot’s documentation for service templates.

4. Installing from Source Code (For Developers)

Obtaining Source Code

git clone https://GitHub.com/clawdbot/clawdbot.git
cd clawdbot

Installing Dependencies

pnpm install  # Requires pnpm (install via `npm install -g pnpm`)

Building the Project

pnpm build

Running ClawDBot

node dist/entry.js gateway

Note: Source installs require manual PATH setup. The official script or npm install is recommended for production use.

5. Containerized Deployment with Docker (Optional)

Pulling the Image

docker pull clawdbot/clawdbot:latest

Running the Container

docker run -d \
  --name clawdbot \
  -p 18789:18789 \
  -v ~/clawd:/root/clawd \
  clawdbot/clawdbot

Configuring Inside the Container

docker exec -it clawdbot clawdbot onboard

Persisting Data

Mount a host directory (e.g., ~/clawd) to /root/clawd in the container to retain configs and chat history across restarts.

6. Common Issues and Solutions

7. Best Practices and Learning Path

• Learn Core Concepts: Understand Gateways, Channels, and Skills via official docs.

• Start Simple: Begin with one channel (e.g., Telegram) and a basic AI model.

• Expand Gradually: Add skills/plugins for advanced automation (e.g., file processing, webhooks).

• Secure Your Data: Never expose the dashboard (127.0.0.1:18789) to public networks. Use firewalls.

• Stay Updated: Run clawdbot update regularly for security patches and new features.

Final Tip: The official installation script handles 90% of setup complexity. Use it unless you have specific developer needs!