# OpenClaw Auto-Login Automation

Cross-platform zero-interaction login for the OpenClaw dashboard.

## Overview

This automation follows the **"How to connect"** steps from the OpenClaw dashboard:

1. **Start the gateway** on your host machine (`openclaw gateway run`)
2. **Get a tokenized dashboard URL** (`openclaw dashboard --no-open`)
3. **Open the browser** with the authenticated URL

## Features

- ✅ **Zero user interaction** - Fully automated login
- ✅ **Cross-platform** - Works on Windows, macOS, and Linux
- ✅ **Smart gateway handling** - Starts gateway if not running
- ✅ **Port conflict resolution** - Automatically detects and kills processes using port 18789
- ✅ **Token extraction** - Automatically gets authenticated URL
- ✅ **Browser detection** - Uses system default or specified browser
- ✅ **Fallback modes** - Multiple strategies for gateway startup

## Usage

### Prerequisites

Install `openclaw-installer` using **pipx** (recommended for isolated environment):

```bash
# Install pipx first (see https://pipx.pypa.io/stable/installation/)
# Then install openclaw-installer
pipx install openclaw-installer
```

### Via CLI

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

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

# Open dashboard with auto-login (alias)
openclaw-installer dashboard

# Skip auto-login and use standard behavior
openclaw-installer dashboard --no-auto-login
```

### Via Python

```python
from openclaw_installer.automation.auto_login import auto_login

# Auto-login with defaults
success = auto_login()

# Auto-login with specific browser
success = auto_login(browser_path="/path/to/browser")

# Auto-login with custom timeout
success = auto_login(startup_timeout=60)
```

### Via Shell Scripts

**Windows (PowerShell):**
```powershell
.\auto-login.ps1
.\auto-login.ps1 -BrowserPath "C:\Program Files\Google\Chrome\Application\chrome.exe"
```

**Linux/macOS (Bash):**
```bash
./auto-login.sh
./auto-login.sh -b /usr/bin/google-chrome
```

## Configuration

Add automation settings to your `openclaw.yaml`:

```yaml
# ... other config ...

automation:
  # Automatically open dashboard after installation
  auto_open_dashboard: true
  
  # Automatically login without manual token entry
  auto_login: true
  
  # Path to browser executable (empty = system default)
  browser_path: ""
  
  # Seconds to wait for gateway startup
  startup_timeout: 30
```

### Platform-Specific Browser Paths

**Windows:**
```yaml
automation:
  browser_path: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
  # or: "C:\\Program Files\\Mozilla Firefox\\firefox.exe"
  # or: "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
```

**macOS:**
```yaml
automation:
  browser_path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  # or: "/Applications/Firefox.app/Contents/MacOS/firefox"
  # or: "/Applications/Safari.app/Contents/MacOS/Safari"
```

**Linux:**
```yaml
automation:
  browser_path: "/usr/bin/google-chrome"
  # or: "/usr/bin/firefox"
  # or: "/usr/bin/chromium"
```

## Platform Support

| Feature | Windows | macOS | Linux |
|---------|---------|-------|-------|
| Gateway Service Start | ✅ | ✅ | ✅ |
| Gateway Background Run | ✅ | ✅ | ✅ |
| Browser Auto-Detection | ✅ | ✅ | ✅ |
| Token Extraction | ✅ | ✅ | ✅ |
| PowerShell Script | ✅ | ❌ | ❌ |
| Bash Script | ❌ | ✅ | ✅ |

## How It Works

### Step 1: Gateway Check
- Checks if `openclaw gateway status` returns "running"
- If not running, attempts to start via service or background process

### Step 2: Token Acquisition
- Runs `openclaw dashboard --no-open`
- Parses output for authenticated URL with token
- Falls back to default URL if token not available

### Step 3: Browser Launch
- **Windows**: Uses `webbrowser` module or `Start-Process`
- **macOS**: Uses `open` command
- **Linux**: Uses `xdg-open`, `gnome-open`, `kde-open`, or `webbrowser`

## Port Conflict Resolution

The auto-login automatically detects and resolves port conflicts on port 18789:

### Detection Methods

| Platform | Command Used |
|----------|-------------|
| **Windows** | `Get-NetTCPConnection`, `netstat -ano` |
| **macOS** | `lsof -i :18789` |
| **Linux** | `ss -tlnp`, `netstat -tlnp` |

### Automatic Resolution

When a conflict is detected, the automation will:
1. Identify the process using port 18789
2. Display the process name and PID
3. Terminate the process (with `taskkill` on Windows, `kill` on Unix)
4. Wait 2 seconds for the port to be released
5. Verify the port is now available
6. Proceed with gateway startup

### Manual Port Check

```bash
# Windows
netstat -ano | findstr :18789

# macOS
lsof -i :18789

# Linux
ss -tlnp sport = :18789
```

### Disable Auto-Kill

To disable automatic port conflict resolution:

```python
from openclaw_installer.automation.auto_login import start_gateway_service

# Set force_kill_conflicts=False
start_gateway_service(wrapper, force_kill_conflicts=False)
```

## Troubleshooting

### "Gateway not responding"
- Check that OpenClaw is properly installed
- Try running `openclaw gateway run` manually
- Increase `startup_timeout` in config

### "Browser not opening"
- Specify full path to browser in config
- Check browser permissions
- Try running with `--verbose` flag

### "Token not found"
- Ensure gateway is fully started before auto-login
- Check `openclaw dashboard --no-open` output manually
- May need to login once manually to initialize

## Integration with Installation

Auto-login runs automatically after installation if configured:

```yaml
automation:
  auto_open_dashboard: true
  auto_login: true
```

The dashboard will open immediately after `openclaw-installer install` completes!

## API Reference

### `auto_login()`

Main function for automated dashboard login.

**Parameters:**
- `browser_path` (str, optional): Path to browser executable
- `startup_timeout` (int): Seconds to wait for gateway (default: 30)
- `verbose` (bool): Show detailed output (default: False)

**Returns:**
- `bool`: True if successful, False otherwise

### `check_gateway_status()`

Check if gateway is running.

**Returns:**
- `bool`: True if running, False otherwise

### `get_tokenized_url()`

Get authenticated dashboard URL.

**Returns:**
- `str | None`: URL with token, or None if unavailable
