openclaw-ansible/docs/development-mode.md

Development Mode Installation

This guide explains how to install Clawdbot in development mode, where the application is built from source instead of installed from npm.

Overview

Release Mode vs Development Mode

Feature	Release Mode	Development Mode
Source	npm registry	GitHub repository
Installation	pnpm install -g clawdbot@latest	git clone + pnpm build
Location	~/.local/share/pnpm/global/...	~/code/clawdbot/
Binary	Global pnpm package	Symlink to bin/clawdbot.js
Updates	pnpm install -g clawdbot@latest	git pull + pnpm build
Use Case	Production, stable deployments	Development, testing, debugging
Recommended For	End users	Developers, contributors

Installation

Quick Install

# Clone the ansible installer
git clone https://github.com/pasogott/clawdbot-ansible.git
cd clawdbot-ansible

# Run in development mode
./run-playbook.sh -e clawdbot_install_mode=development

Manual Install

# Install ansible
sudo apt update && sudo apt install -y ansible git

# Clone repository
git clone https://github.com/pasogott/clawdbot-ansible.git
cd clawdbot-ansible

# Install collections
ansible-galaxy collection install -r requirements.yml

# Run playbook with development mode
ansible-playbook playbook.yml --ask-become-pass -e clawdbot_install_mode=development

What Gets Installed

Directory Structure

/home/clawdbot/
├── .clawdbot/              # Configuration directory
│   ├── sessions/
│   ├── credentials/
│   ├── data/
│   └── logs/
├── .local/
│   ├── bin/
│   │   └── clawdbot       # Symlink -> ~/code/clawdbot/bin/clawdbot.js
│   └── share/pnpm/
└── code/
    └── clawdbot/          # Git repository
        ├── bin/
        │   └── clawdbot.js
        ├── dist/          # Built files
        ├── src/           # Source code
        ├── package.json
        └── pnpm-lock.yaml

Installation Steps

The Ansible playbook performs these steps:

1. Create ~/code directory

   mkdir -p ~/code
   

2. Clone repository

   cd ~/code
   git clone https://github.com/clawdbot/clawdbot.git
   

3. Install dependencies

   cd clawdbot
   pnpm install
   

4. Build from source

   pnpm build
   

5. Create symlink

   ln -sf ~/code/clawdbot/bin/clawdbot.js ~/.local/bin/clawdbot
   chmod +x ~/code/clawdbot/bin/clawdbot.js
   

6. Add development aliases to .bashrc:

   alias clawdbot-rebuild='cd ~/code/clawdbot && pnpm build'
   alias clawdbot-dev='cd ~/code/clawdbot'
   alias clawdbot-pull='cd ~/code/clawdbot && git pull && pnpm install && pnpm build'
   

Development Workflow

Making Changes

# 1. Navigate to repository
clawdbot-dev
# or: cd ~/code/clawdbot

# 2. Make your changes
vim src/some-file.ts

# 3. Rebuild
clawdbot-rebuild
# or: pnpm build

# 4. Test immediately
clawdbot --version
clawdbot doctor

Pulling Updates

# Pull latest changes and rebuild
clawdbot-pull

# Or manually:
cd ~/code/clawdbot
git pull
pnpm install
pnpm build

Testing Changes

# After rebuilding, the clawdbot command uses the new code immediately
clawdbot status
clawdbot gateway

# View daemon logs
clawdbot logs

Switching Branches

cd ~/code/clawdbot

# Switch to feature branch
git checkout feature-branch
pnpm install
pnpm build

# Switch back to main
git checkout main
pnpm install
pnpm build

Development Aliases

The following aliases are added to .bashrc:

Alias	Command	Purpose
clawdbot-dev	cd ~/code/clawdbot	Navigate to repo
clawdbot-rebuild	cd ~/code/clawdbot && pnpm build	Rebuild after changes
clawdbot-pull	cd ~/code/clawdbot && git pull && pnpm install && pnpm build	Update and rebuild

Plus an environment variable:

export CLAWDBOT_DEV_DIR="$HOME/code/clawdbot"

Configuration Variables

You can customize the development installation:

# In playbook or command line
clawdbot_install_mode: "development"
clawdbot_repo_url: "https://github.com/clawdbot/clawdbot.git"
clawdbot_repo_branch: "main"
clawdbot_code_dir: "/home/clawdbot/code"
clawdbot_repo_dir: "/home/clawdbot/code/clawdbot"

Using a Fork

ansible-playbook playbook.yml --ask-become-pass \
  -e clawdbot_install_mode=development \
  -e clawdbot_repo_url=https://github.com/YOUR_USERNAME/clawdbot.git \
  -e clawdbot_repo_branch=your-feature-branch

Custom Location

ansible-playbook playbook.yml --ask-become-pass \
  -e clawdbot_install_mode=development \
  -e clawdbot_code_dir=/home/clawdbot/projects

Switching Between Modes

From Release to Development

# Uninstall global package
pnpm uninstall -g clawdbot

# Run ansible in development mode
ansible-playbook playbook.yml --ask-become-pass -e clawdbot_install_mode=development

From Development to Release

# Remove symlink
rm ~/.local/bin/clawdbot

# Remove repository (optional)
rm -rf ~/code/clawdbot

# Install from npm
pnpm install -g clawdbot@latest

Troubleshooting

Build Fails

cd ~/code/clawdbot

# Check Node.js version (needs 22.x)
node --version

# Clean install
rm -rf node_modules
pnpm install
pnpm build

Symlink Not Working

# Check symlink
ls -la ~/.local/bin/clawdbot

# Recreate symlink
rm ~/.local/bin/clawdbot
ln -sf ~/code/clawdbot/bin/clawdbot.js ~/.local/bin/clawdbot
chmod +x ~/code/clawdbot/bin/clawdbot.js

Command Not Found

# Ensure ~/.local/bin is in PATH
echo $PATH | grep -q ".local/bin" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Git Issues

cd ~/code/clawdbot

# Reset to clean state
git reset --hard origin/main
git clean -fdx

# Rebuild
pnpm install
pnpm build

Performance Considerations

Build Time

First build takes longer (~1-2 minutes depending on system):

pnpm install    # Downloads dependencies
pnpm build      # Compiles TypeScript

Subsequent rebuilds are faster (~10-30 seconds):

pnpm build      # Only recompiles changed files

Disk Usage

Development mode uses more disk space:

• Release mode: ~150 MB (global pnpm cache)
• Development mode: ~400 MB (repo + node_modules + dist)

Memory Usage

No difference in runtime memory usage between modes.

CI/CD Integration

Testing Before Merge

# Test specific commit
cd ~/code/clawdbot
git fetch origin pull/123/head:pr-123
git checkout pr-123
pnpm install
pnpm build

# Test it
clawdbot doctor

Automated Testing

#!/bin/bash
# test-clawdbot.sh

cd ~/code/clawdbot
git pull
pnpm install
pnpm build

# Run tests
pnpm test

# Integration test
clawdbot doctor

Best Practices

Development Workflow

1. ✅ Always rebuild after code changes

   clawdbot-rebuild
   

2. ✅ Test changes before committing

   pnpm build && clawdbot doctor
   

3. ✅ Keep dependencies updated

   pnpm update
   pnpm build
   

4. ✅ Use feature branches

   git checkout -b feature/my-feature
   

Don't Do

• ❌ Editing code without rebuilding
• ❌ Running pnpm link manually (breaks setup)
• ❌ Installing global packages while in dev mode
• ❌ Modifying symlink manually

Advanced Usage

Multiple Repositories

You can have multiple clones:

# Main development
~/code/clawdbot/          # main branch

# Experimental features
~/code/clawdbot-test/     # testing branch

# Switch binary symlink
ln -sf ~/code/clawdbot-test/bin/clawdbot.js ~/.local/bin/clawdbot

Custom Build Options

cd ~/code/clawdbot

# Development build (faster, includes source maps)
NODE_ENV=development pnpm build

# Production build (optimized)
NODE_ENV=production pnpm build

Debugging

# Run with debug output
DEBUG=* clawdbot gateway

# Or specific namespaces
DEBUG=clawdbot:* clawdbot gateway

See Also

• Main README
• Security Architecture
• Troubleshooting Guide
• Clawdbot Repository