Metadata-Version: 2.4
Name: openclaw-installer
Version: 1.0.5
Summary: Zero-config installer for OpenClaw AI assistant - works with Kimi, Claude, GPT, and local models
Project-URL: Homepage, https://github.com/openclaw/openclaw-installer
Project-URL: Documentation, https://github.com/openclaw/openclaw-installer#readme
Project-URL: Repository, https://github.com/openclaw/openclaw-installer
Project-URL: Issues, https://github.com/openclaw/openclaw-installer/issues
Author-email: Gerald Enrique Nelson Mc Kenzie <lordxmen2k@gmail.com>
License: MIT
Keywords: ai,assistant,automation,claude,installer,kimi,openclaw
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🦞 OpenClaw Installer

**Zero-config installer for OpenClaw AI assistant**

Install and configure [OpenClaw](https://openclaw.ai) — the AI that actually does things — with a single command. Works with **Kimi (Moonshot AI)**, Claude, GPT-4, OpenRouter, and local Ollama models.

---

## ✨ Features

- **One-command install** — No manual Node.js setup
- **Multiple AI providers** — Kimi, Claude, GPT-4, OpenRouter, Ollama  
- **Cross-platform** — Windows, macOS, Linux
- **Bundled Node.js** — Uses `nodejs-bin`, no external dependencies
- **Simple YAML config** — One file, zero coding
- **Auto-starts gateway** — Ready to use immediately

---

## 🚀 Quick Start

> **Windows Users:** Run PowerShell as Administrator (required for npm global installs)

### 1. Install pipx (if not already installed)

**pipx** runs the installer in an isolated environment, avoiding dependency conflicts with other Python packages.

**Install pipx:**
- **macOS/Linux:** https://pipx.pypa.io/stable/installation/#installing-pipx
- **Windows:** https://pipx.pypa.io/stable/installation/#install-on-windows

Or install via package manager:
```bash
# macOS
brew install pipx
pipx ensurepath

# Linux (Debian/Ubuntu)
sudo apt install pipx
pipx ensurepath

# Linux (Fedora)
sudo dnf install pipx
pipx ensurepath

# Windows (requires Python 3.8+)
python -m pip install --user pipx
python -m pipx ensurepath
```

### 2. Install OpenClaw Installer

```bash
pipx install openclaw-installer
```

**Note:** If you see a PATH warning like:
```
⚠️  Note: '/Users/username/.local/bin' is not on your PATH environment variable.
```

Run this to fix it:
```bash
pipx ensurepath
```

Then **restart your terminal** or run:
```bash
source ~/.zshrc   # For macOS Catalina and later (zsh)
# or
source ~/.bashrc  # For older macOS or if using bash
```

### 2. Configure

Create `openclaw.yaml`:

```yaml
ai:
  provider: anthropic  # or openai, kimi, ollama
  key: "your-api-key"

channels:
  web: true

gateway:
  autostart: true
```

### 3. Install OpenClaw

```bash
# Linux/Mac
openclaw-installer install --config openclaw.yaml

# Windows (PowerShell as Administrator)
openclaw-installer install --config openclaw.yaml
```## 1. Install pipx (if not already installed)

See [Quick Start](#1-install-pipx-if-not-already-installed) above for pipx installation instructions.

## 2. Install OpenClaw Installer

```bash
pipx install openclaw-installer
```

### 2. Generate a config

```bash
openclaw-installer generate-config > openclaw.yaml
```

### 3. Edit the config

```yaml
ai:
  provider: kimi           # or anthropic, openai, ollama
  key: "sk-your-key-here"  # Get from https://platform.moonshot.cn/

channels:
  web: true

gateway:
  autostart: true
```

### 4. Install OpenClaw

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

### 5. Open Dashboard

```bash
openclaw dashboard
# or visit: http://localhost:18789
```

Done! 🎉

---

## ⚡ vs Official OpenClaw CLI

**Why use this installer instead of `npm install -g openclaw && openclaw onboard`?**

| Feature | Official Wizard | This Installer |
|---------|-----------------|----------------|
| **Node.js required?** | ✅ Yes (install manually) | ❌ **No** (bundled automatically) |
| **Installation style** | Interactive prompts | **YAML config** (unattended) |
| **CI/CD automation** | ❌ Manual only | ✅ **Fully automated** |
| **Repeatable deploys** | ❌ Answer prompts each time | ✅ **Idempotent** |
| **Non-technical users** | Must understand Node/npm | ✅ **Edit a file, run a command** |
| **Version control** | ❌ Interactive state | ✅ **Config in git** |
| **Dependency isolation** | ❌ pip (potential conflicts) | ✅ **pipx (isolated env)** |

### When to Use This Installer

✅ **Perfect for:**
- Teams sharing standard setups
- Docker containers / cloud VMs
- CI/CD pipelines
- Non-technical users who just want it to work
- Repeatable deployments across multiple machines

✅ **Example scenario:**
```bash
# Deploy to 50 company laptops
# 1. Share openclaw.yaml with API key
# 2. One command: pipx install openclaw-installer && openclaw-installer install --config openclaw.yaml
# 3. Everyone has identical setup
```

### When to Use Official Wizard Instead

⚠️ **Better choice when:**
- Exploring OpenClaw for the first time
- Need hand-holding through provider selection
- Already have Node.js installed and prefer interactive setup
- Want to customize every option manually

### Community Context

This package fills a specific gap:
- **Available on PyPI:** Package name `openclaw-installer` is reserved and ready
- **Community demand:** Existing GitHub projects like `miaoxworld/OpenClawInstaller` and `Personal-MT-Engineering/openClaw-install` show users want easier installation
- **Different from `armorer`:** That tool focuses on security sandboxing; this focuses on **ease-of-use**

**Bottom line:** After this installer runs, you use the **same** OpenClaw dashboard/CLI as everyone else. We're just the "easy on-ramp."

---

## 🖥️ Using the OpenClaw Dashboard

The Dashboard (Control UI) is your central hub for managing OpenClaw.

### Opening the Dashboard

| Method | Command |
|--------|---------|
| CLI | `openclaw dashboard` |
| Auto-Login | `openclaw-installer auto-login` |
| Browser | http://localhost:18789 |
| Auto-open | Enabled by default after install |

### Auto-Login (Zero-Interaction)

The auto-login feature automatically connects to the dashboard **without requiring manual token entry**. It follows the "How to connect" steps:

1. **Start the gateway** on your host machine
2. **Get a tokenized dashboard URL** 
3. **Open the browser** with the authenticated URL

```bash
# Auto-login with default browser
openclaw-installer auto-login

# Auto-login with specific browser
openclaw-installer auto-login --browser "/path/to/chrome"

# Open dashboard with auto-login (same as above)
openclaw-installer dashboard
```

**Cross-Platform Support:**
- ✅ **Windows**: PowerShell script + Python automation
- ✅ **macOS**: Bash script + Python automation  
- ✅ **Linux**: Bash script + Python automation

**Configure in your YAML:**
```yaml
automation:
  auto_open_dashboard: true  # Auto-open after install
  auto_login: true           # Skip manual token entry
  browser_path: ""           # Use system default
  startup_timeout: 30        # Seconds to wait for gateway
```

### Dashboard Sections

#### 🤖 Agents Panel
- **Create Agents**: Build specialized AI agents for different tasks
- **Configure Memory**: Set context windows and persistence
- **Agent Teams**: Group agents for collaborative workflows
- **Skills**: Install/enable capabilities (web search, code execution, etc.)

#### 💬 Conversations
- Chat with your AI across all connected channels
- View conversation history
- Export/backup important chats

#### 🔌 Integrations (Channels)
- **Web UI**: Always available at `http://localhost:18789`
- **WhatsApp**: Pair by scanning QR code
- **Telegram**: Configure bot token
- **Discord**: Add bot to servers
- **Slack**: Install workspace app
- **iMessage**: macOS only (requires Full Disk Access)

#### ⚙️ Settings
- **AI Provider**: Switch between Claude, GPT, Kimi, Ollama
- **Model Selection**: Choose specific models per task
- **System Prompts**: Customize agent behavior
- **Memory**: Configure long-term storage
- **Gateway**: Port, logging, security settings

### First-Time Setup in Dashboard

1. **Verify AI Connection**: Settings → AI → Test Connection
2. **Enable Skills**: Agents → Skills → Install (see below)
3. **Create First Agent**: Agents → New → Select skills
4. **Test Chat**: Conversations → New → Send test message

---

## 🤖 Supported AI Providers

| Provider | Model Example | Setup | Best For |
|----------|---------------|-------|----------|
| **Kimi** (Moonshot AI) | `kimi-k2.5` | [platform.moonshot.cn](https://platform.moonshot.cn/) | Chinese/English, 256K context |
| **Anthropic** | `claude-3-5-sonnet` | [console.anthropic.com](https://console.anthropic.com/) | Coding, reasoning |
| **OpenAI** | `gpt-4o` | [platform.openai.com](https://platform.openai.com/) | General tasks |
| **OpenRouter** | `anthropic/claude-3.5-sonnet` | [openrouter.ai](https://openrouter.ai/) | Model flexibility |
| **Ollama** | `llama3.2` | [ollama.ai](https://ollama.ai/) | Privacy, offline |

---

## 📁 Example Configurations

### Kimi (Moonshot AI)

```yaml
ai:
  provider: kimi
  key: "sk-your-moonshot-key"
  model: "kimi-k2.5"

channels:
  web: true
  telegram: true
  telegram_token: "${TELEGRAM_BOT_TOKEN}"
```

### Claude with all channels

```yaml
ai:
  provider: anthropic
  key: "${ANTHROPIC_API_KEY}"
  model: "claude-3-5-sonnet"

channels:
  web: true
  whatsapp: true
  telegram: true
  telegram_token: "your-bot-token"
```

### Local Ollama (offline)

```yaml
ai:
  provider: ollama
  key: ""  # No key needed
  model: "llama3.2"

gateway:
  port: 18789
```

---

## 🛠️ Commands

| Command | Description |
|---------|-------------|
| `openclaw-installer install --config file.yaml` | Install OpenClaw from config |
| `openclaw-installer generate-config` | Print example config |
| `openclaw-installer generate-config -o config.yaml` | Save example config |
| `openclaw-installer uninstall` | Remove OpenClaw |
| `openclaw-installer auto-login` | **Auto-login to dashboard (zero-interaction)** |
| `openclaw-installer dashboard` | Open web dashboard with auto-login |
| `openclaw dashboard` | Open web dashboard (standard) |
| `openclaw gateway status` | Check if gateway running |
| `openclaw daemon start/stop` | Control background service |
| `openclaw logs` | View logs |
| `--dry-run` | Simulate without changes |

### Upgrading

```bash
pipx upgrade openclaw-installer
```

### Uninstalling

```bash
pipx uninstall openclaw-installer
```

---

## 🛡️ Best Practices

### 🔐 Security

#### API Key Management
```yaml
# ✅ GOOD: Use environment variables
ai:
  key: "${ANTHROPIC_API_KEY}"  # Reads from env var

# ❌ BAD: Hardcoded key
ai:
  key: "sk-ant-api03-actual-key-here"
```

Set environment variables:
```bash
# Linux/macOS
export ANTHROPIC_API_KEY="sk-ant-..."
export KIMI_API_KEY="sk-..."

# Windows PowerShell
$env:ANTHROPIC_API_KEY="sk-ant-..."

# Windows CMD
set ANTHROPIC_API_KEY=sk-ant-...
```

#### Gateway Security
- **Default**: Runs on `127.0.0.1` (localhost only) — SAFE
- **Remote access**: Set `host: 0.0.0.0` only with authentication
- **Firewall**: Block port 18789 from external networks unless needed

```yaml
# Local only (secure default)
gateway:
  host: 127.0.0.1
  port: 18789

# Remote access (use with caution)
gateway:
  host: 0.0.0.0  # Accessible from network
  port: 18789
  # Add reverse proxy with auth (nginx/traefik)
```

#### File System Permissions
```bash
# Workspace should be user-readable only
chmod 700 ~/openclaw-workspace

# Config files with API keys
chmod 600 openclaw.yaml
```

---

### 🧩 Installing & Managing Skills

Skills extend OpenClaw capabilities (web search, code execution, file operations).

#### Via Dashboard (Recommended)
1. Open Dashboard: `openclaw dashboard`
2. Navigate: **Agents → Skills**
3. Browse skill marketplace
4. Click **Install** on desired skills
5. Configure skill settings

#### Via CLI
```bash
# List available skills
openclaw skills list

# Install a skill
openclaw skills install web-search
openclaw skills install code-execution
openclaw skills install file-manager

# Enable/disable
openclaw skills enable web-search
openclaw skills disable code-execution
```

#### Essential Skills
| Skill | Purpose | Install |
|-------|---------|---------|
| `web-search` | Search Google/DuckDuckGo | `openclaw skills install web-search` |
| `code-execution` | Run code safely | `openclaw skills install code-execution` |
| `file-manager` | Read/write files | Built-in |
| `browser` | Web browsing | `openclaw skills install browser` |
| `memory` | Long-term memory | Built-in |

#### Custom Skills
Create custom skills in your workspace:
```bash
mkdir -p ~/openclaw-workspace/skills/my-skill
cd ~/openclaw-workspace/skills/my-skill
```

Create `skill.yaml`:
```yaml
name: my-custom-skill
description: Does something awesome
version: 1.0.0
entry: main.py
```

Create `main.py`:
```python
def run(command: str) -> str:
    """Execute the skill."""
    return f"Executed: {command}"
```

---

### 👥 Creating Agent Teams

Agent teams let multiple specialized agents collaborate on complex tasks.

#### Dashboard Method
1. **Agents → Teams → Create Team**
2. Add agents with specific roles:
   - **Researcher**: Web search, data gathering
   - **Coder**: Code execution, debugging
   - **Writer**: Documentation, summaries
   - **Reviewer**: Quality checks

3. Set **Orchestrator**: The lead agent that delegates tasks

#### Example: Development Team
```yaml
# Team configuration (in Dashboard)
team:
  name: "Dev Team"
  orchestrator: "tech-lead"
  agents:
    - name: "tech-lead"
      model: "claude-3-5-sonnet"
      skills: ["planning", "architecture"]

    - name: "code-reviewer"
      model: "claude-3-5-sonnet"
      skills: ["code-review", "security-audit"]

    - name: "researcher"
      model: "gpt-4o"
      skills: ["web-search", "documentation"]
```

#### CLI Method
```bash
# Create team
openclaw teams create dev-team --orchestrator tech-lead

# Add agents
openclaw teams add dev-team tech-lead --model claude-3-5-sonnet
openclaw teams add dev-team code-reviewer --model claude-3-5-sonnet
openclaw teams add dev-team researcher --model gpt-4o

# Activate team
openclaw teams use dev-team
```

---

### 🔗 Nodes (Distributed OpenClaw)

Nodes allow running OpenClaw across multiple machines for load distribution or specialized hardware.

#### Use Cases
- **GPU Node**: Remote machine with GPU for local AI (Ollama)
- **Cloud Node**: VPS running 24/7 for webhooks
- **Home Node**: Raspberry Pi for always-on gateway

#### Setting Up a Node

**On Node Machine:**
```bash
# Install OpenClaw with node role
openclaw-installer install --config node-config.yaml

# Expose node (behind firewall/VPN recommended)
openclaw node serve --port 18790 --token SECURE_TOKEN
```

**On Main Machine:**
```yaml
# main-config.yaml
nodes:
  - name: "gpu-server"
    url: "http://192.168.1.100:18790"
    token: "SECURE_TOKEN"
    capabilities: ["ollama", "gpu"]

  - name: "cloud-vps"
    url: "https://vps.example.com:18790"
    token: "SECURE_TOKEN"
    capabilities: ["webhook", "always-on"]

# Route specific tasks to nodes
routing:
  ollama-requests: "gpu-server"
  webhook-handlers: "cloud-vps"
```

#### Node Commands
```bash
# List connected nodes
openclaw nodes list

# Check node health
openclaw nodes status gpu-server

# Send command to specific node
openclaw nodes exec gpu-server "ollama list"
```

---

### 💾 Backup & Migration

#### What to Backup
```bash
# Configuration
cp openclaw.yaml ~/backups/

# Workspace (agents, memory, skills)
tar -czf openclaw-backup.tar.gz ~/openclaw-workspace/

# Environment variables
env | grep OPENCLAW > openclaw-env.txt
```

#### Restore
```bash
# Restore workspace
tar -xzf openclaw-backup.tar.gz -C ~/

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

---

### 🚀 Performance Optimization

#### For Fast Response
```yaml
ai:
  provider: anthropic
  model: "claude-3-5-haiku"  # Faster than sonnet
```

#### For Complex Tasks
```yaml
ai:
  provider: anthropic  
  model: "claude-3-opus"  # Best reasoning
```

#### Local AI (Privacy + Speed)
```yaml
ai:
  provider: ollama
  model: "llama3.2"  # Runs offline, no latency
```

---

### 🔧 Troubleshooting

#### Dashboard Won't Load
```bash
# Check gateway status
openclaw gateway status

# Restart gateway
openclaw daemon restart

# Check logs
openclaw logs | tail -50
```

#### API Key Not Working
```bash
# Test directly
export OPENCLAW_API_KEY="your-key"
openclaw config set ai.apiKey "$OPENCLAW_API_KEY"
openclaw config test-connection
```

#### Reset Everything
```bash
# Uninstall and clean
openclaw-installer uninstall
rm -rf ~/openclaw-workspace

# Fresh install
openclaw-installer install --config openclaw.yaml
```

---

## 📋 Requirements

- Python 3.9+
- No Node.js required (bundled)
- No npm required (bundled)

---

## 📄 License

MIT License

---

**Not affiliated with OpenClaw.** This is a community installer.
