Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Clawdbot is a WhatsApp gateway and AI agent system that requires a specific Node.js environment and configuration sequence to function as a bridge between messaging channels and AI providers. The installation process covers environment preparation, dependency management, and a multi-flow onboarding system that configures gateways, agents, and authentication monitoring.
The system supports multiple installation modes, including local deployment, remote gateway connections, and containerized environments for testing and production. Configuration is managed through a central clawdbot.json file, which is scaffolded during the initial onboarding process.
Prerequisites and Environment
Before installing Clawdbot, the host system must meet specific runtime requirements and have necessary package managers available.
System Requirements
- Runtime: Node.js version 22+ is the mandatory baseline for executing the built output and production installs.
- Package Managers: The project supports
pnpm(version 10.23.0 recommended) andbunfor development and dependency synchronization. - Operating Systems: Supported across macOS, Linux, and specialized environments like Termux (Android).
Sources: CLAUDE.md:43-52, package.json:181-184
Dependency Setup
Dependencies are managed primarily through pnpm. A post-install script is executed to handle environment-specific configurations.
pnpm install
Sources: CLAUDE.md:45, package.json:84
Installation Flows
Clawdbot provides several installation pathways depending on the intended use case.
1. Global CLI Installation
For production use on servers or local machines, the CLI can be installed globally via npm. This requires root permissions for directory access.
sudo npm i -g clawdbot@latest
Sources: CLAUDE.md:32-34
2. Onboarding Wizard
The onboard command initiates an interactive or non-interactive setup wizard. It scaffolds the workspace, identifies the user, and configures the gateway mode.
The onboarding process creates the following directory structure:
- Config:
~/.clawdbot/clawdbot.json - Sessions:
~/.clawdbot/agents/main/sessions - Workspace:
~/clawd/(contains AGENTS.md, IDENTITY.md, SOUL.md, etc.)
Sources: scripts/e2e/onboard-docker.sh:163-183, CLAUDE.md:104-106
3. Docker Installation (E2E/Testing)
A Docker-based installation is available for end-to-end testing, utilizing a specific Dockerfile to create a clean environment for the onboarding flow.
Sources: scripts/e2e/onboard-docker.sh:6-10
Configuration Management
The system behavior is governed by the clawdbot.json file. Key configuration sections include gateway modes and service settings.
| Configuration Key | Type | Default/Options | Description |
|---|---|---|---|
gateway.mode | String | local | remote | Determines if the bot runs locally or connects to a remote instance. |
gateway.bind | String | loopback | Network binding for the gateway listener. |
gateway.port | Number | 18789 | Port for the gateway websocket connection. |
agents.defaults.workspace | String | ~/clawd | Path to the default AI agent workspace. |
skills.install.nodeManager | String | bun | pnpm | Tool used to manage skill/plugin dependencies. |
Sources: scripts/e2e/onboard-docker.sh:185-225, CLAUDE.md:36-37
Authentication System Setup
Clawdbot includes a specialized authentication management system, particularly for Claude Code integration and long-lived tokens.
Setup Script
The setup-auth-system.sh script automates the creation of long-lived API tokens and configures monitoring services.
Auth Components
- Status Checker:
scripts/claude-auth-status.sh - Mobile Re-auth:
scripts/mobile-reauth.shfor Termux-based quick authentication. - Monitoring: A systemd timer that checks token expiry every 30 minutes.
Sources: scripts/setup-auth-system.sh:11-92
Gateway Initialization and Verification
Once configured, the gateway must be started to enable messaging channel processing.
Starting the Gateway
The gateway can be run via the CLI with optional binding and port overrides. In production environments, it is typically run as a background process.
nohup clawdbot gateway run --bind loopback --port 18789 --force > /tmp/clawdbot-gateway.log 2>&1 &
Sources: CLAUDE.md:38-40
Verification Commands
To ensure the installation was successful and the gateway is listening:
- Status Probe:
clawdbot channels status --probe - Port Check:
ss -ltnp | rg 18789 - Logs:
tail -n 120 /tmp/clawdbot-gateway.log
Sources: CLAUDE.md:41
Conclusion
The installation of Clawdbot transitions from basic Node.js environment preparation to a specialized onboarding flow that establishes a secure workspace for AI agents. By utilizing global CLI tools for production and automated shell scripts for authentication persistence, Clawdbot ensures a stable connection between local compute resources and remote AI/messaging providers.