# SETUP.md — Local Development & Testing Guide

Complete guide to set up `openclaw-installer` for development and testing on **Windows, macOS, and Linux**.

---

## 📋 Prerequisites

| Platform | Requirements |
|----------|-------------|
| **Windows** | Python 3.9+, Git Bash or PowerShell, optional: WSL2 |
| **macOS** | Python 3.9+, Xcode Command Line Tools |
| **Linux** | Python 3.9+, `python3-dev` package |

---

## 🐍 Python Setup (All Platforms)

### Check Python Version

```bash
python --version  # or python3 --version
# Should be 3.9 or higher
```

If Python is missing:
- **Windows**: Download from https://python.org (check "Add to PATH")
- **macOS**: `brew install python@3.11` or https://python.org
- **Linux**: `sudo apt install python3 python3-pip python3-venv`

---

## 🧪 Virtual Environment Setup

### Step 1: Clone Repository

```bash
git clone https://github.com/YOUR_USERNAME/openclaw-installer.git
cd openclaw-installer
```

### Step 2: Create Virtual Environment

**Linux / macOS:**
```bash
python3 -m venv venv
source venv/bin/activate
```

**Windows (PowerShell):**
```powershell
python -m venv venv
.\venv\Scripts\Activate.ps1
# If execution policy error, run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

**Windows (CMD):**
```cmd
python -m venv venv
venv\Scripts\activate.bat
```

**Windows (Git Bash):**
```bash
python -m venv venv
source venv/Scripts/activate
```

### Step 3: Verify Activation

```bash
which python
# Should show: .../openclaw-installer/venv/bin/python

python --version
# Should show: Python 3.9+ or 3.10+ or 3.11+
```

---

## 📦 Install Dependencies

### Development Install (Editable)

```bash
pip install -e .
# or with dev dependencies:
pip install -e ".[dev]"
```

This installs the package in "editable" mode — changes to source are reflected immediately.

### Verify Installation

```bash
openclaw-installer --help
# Should show help text

openclaw-install --help
# Alias also works
```

---

## 🧪 Testing the Installer

### Test 1: Generate Config

```bash
# Print to stdout
openclaw-installer generate-config

# Save to file
openclaw-installer generate-config -o test-config.yaml
cat test-config.yaml  # or type test-config.yaml on Windows
```

### Test 2: Dry Run

Create a minimal test config:

```yaml
# test-dry-run.yaml
ai:
  provider: anthropic
  key: "test-key-123"

channels:
  web: true
```

Run dry run:

```bash
openclaw-installer install --config test-dry-run.yaml --dry-run
```

Expected output:
```
┌ OpenClaw Installer ──────────┐
│                              │
└──────────────────────────────┘
DRY RUN MODE - No changes will be made
[dim]Installing OpenClaw latest...[/] [yellow](skipped)[/]
[dim]Configuring AI provider...[/] [yellow](skipped)[/]
...
```

---

## 🤖 Testing with Real AI Providers

### Test with Kimi (Moonshot AI)

**1. Get API Key:**
- Go to https://platform.moonshot.cn/
- Sign up and create API key
- Copy the key (starts with `sk-`)

**2. Create config:**

```yaml
# test-kimi.yaml
ai:
  provider: kimi
  key: "sk-your-actual-key-here"
  model: "kimi-k2.5"

channels:
  web: true

gateway:
  port: 18789
  autostart: true
```

**3. Run install:**

```bash
openclaw-installer install --config test-kimi.yaml
```

Expected: OpenClaw installs, gateway starts on http://localhost:18789

---

### Test with Ollama (Local, No API Key)

**1. Install Ollama:**

**macOS/Linux:**
```bash
curl -fsSL https://ollama.ai/install.sh | sh
```

**Windows:**
Download from https://ollama.ai/download/windows

**2. Pull a model:**

```bash
ollama pull llama3.2
```

**3. Start Ollama server:**

```bash
ollama serve
# Keep this running in separate terminal
```

**4. Create config:**

```yaml
# test-ollama.yaml
ai:
  provider: ollama
  key: ""  # No key needed
  model: "llama3.2"
  base_url: "http://localhost:11434"

channels:
  web: true

gateway:
  port: 18789
```

**5. Run install:**

```bash
openclaw-installer install --config test-ollama.yaml
```

---

### Test with Anthropic (Claude)

**1. Get API Key:**
- https://console.anthropic.com/

**2. Create config:**

```yaml
# test-claude.yaml
ai:
  provider: anthropic
  key: "sk-ant-api03-your-key"
  model: "claude-3-5-sonnet"

channels:
  web: true
```

**3. Run install:**

```bash
openclaw-installer install --config test-claude.yaml
```

---

## 🖥️ Platform-Specific Testing

### Windows Testing

**Option A: Native Windows**
```powershell
# PowerShell as Administrator (optional, for service install)
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e ".[dev]"
openclaw-installer install --config test-config.yaml
```

**Option B: WSL2 (Recommended for OpenClaw)**
```bash
# In WSL2 Ubuntu
sudo apt update
sudo apt install python3 python3-pip python3-venv
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
openclaw-installer install --config test-config.yaml
```

### macOS Testing

```bash
# Install Python if needed
brew install python@3.11

# Setup
cd openclaw-installer
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Test
openclaw-installer install --config test-config.yaml

# Check gateway is running
openclaw gateway status
```

### Linux Testing

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install python3 python3-pip python3-venv git

# Follow standard setup above
```

**Fedora/RHEL:**
```bash
sudo dnf install python3 python3-pip python3-virtualenv git
# Follow standard setup above
```

**Arch:**
```bash
sudo pacman -S python python-pip python-virtualenv git
# Follow standard setup above
```

---

## 🔄 Uninstall Testing

Test cleanup works properly:

```bash
openclaw-installer uninstall
```

Verify:
```bash
which openclaw
# Should return nothing (not found)
```

---

## 🐛 Debugging

### Enable Verbose Mode

```bash
# Check Node.js bundled with package
python -c "from nodejs import node; print(node('--version', capture_output=True).stdout)"

# Test npm works
python -c "from nodejs import npm; npm('--version')"

# Check openclaw command
which openclaw
openclaw --version
```

### Check Logs

If gateway fails to start:

```bash
openclaw logs
# or
openclaw gateway logs
```

### Reset Everything

```bash
# Stop gateway
openclaw daemon stop

# Uninstall
openclaw-installer uninstall

# Clean npm cache
python -c "from nodejs import npm; npm('cache', 'clean', '--force')"

# Reinstall
openclaw-installer install --config your-config.yaml
```

---

## 🧪 Automated Testing (pytest)

### Run Tests

```bash
pip install pytest
pytest tests/ -v
```

### Test Structure

Create `tests/test_config.py`:

```python
import pytest
from pathlib import Path
from openclaw_installer.config import Config, AIConfig

def test_ai_config_defaults():
    cfg = AIConfig(provider="kimi", key="test")
    assert cfg.provider == "kimi"
    assert cfg.get_base_url() == "https://api.moonshot.cn/v1"
    assert cfg.get_default_model() == "kimi-k2.5"

def test_config_from_yaml(tmp_path):
    yaml_content = """
ai:
  provider: anthropic
  key: "sk-test"
channels:
  web: true
"""
    config_file = tmp_path / "test.yaml"
    config_file.write_text(yaml_content)

    cfg = Config.from_yaml(config_file)
    assert cfg.ai.provider == "anthropic"
    assert cfg.channels.web is True
```

Run:
```bash
pytest tests/ -v
```

---

## 📊 CI Testing Matrix

Test on multiple platforms with GitHub Actions (`.github/workflows/test.yml`):

```yaml
name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python: ["3.9", "3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
      - name: Install
        run: pip install -e ".[dev]"
      - name: Test
        run: pytest tests/ -v
```

---

## ✅ Release Testing Checklist

Before publishing to PyPI, verify:

- [ ] `openclaw-installer --help` works on Windows
- [ ] `openclaw-installer --help` works on macOS  
- [ ] `openclaw-installer --help` works on Linux
- [ ] `generate-config` outputs valid YAML
- [ ] `--dry-run` completes without errors
- [ ] Kimi config validates correctly
- [ ] Claude config validates correctly
- [ ] Ollama config validates correctly
- [ ] Install completes (test on at least one platform with real key)
- [ ] Uninstall removes openclaw command
- [ ] `twine check` passes
- [ ] Version bumped in both `pyproject.toml` and `__init__.py`

---

**Ready to develop! 🚀**
