# Getting Started

## Requirements

- [Bun](https://bun.sh) >= 1.1.0
- [pi CLI](https://github.com/badlogic/pi-mono) (`npm install -g @mariozechner/pi-coding-agent`)
- A configured LLM provider (API key or OAuth via `pi /login`)

## Installation

```bash
# Clone the repository
git clone https://github.com/openclaw/pi-gateway.git
cd pi-gateway

# Install dependencies
bun install

# (Optional) Build standalone binary
bun run build
```

## Quick Start

### 1. Create Configuration

Copy the example configuration:

```bash
cp pi-gateway.jsonc.example pi-gateway.jsonc
```

Edit `pi-gateway.jsonc` and add your bot tokens:

```jsonc
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN"
    }
  }
}
```

Or use environment variables:

```bash
export TELEGRAM_BOT_TOKEN="your-bot-token"
```

### 2. Start the Gateway

```bash
bun run start
```

Or with verbose logging:

```bash
bun run src/cli.ts gateway --verbose
```

### 3. Test the Gateway

```bash
# Health check
bun run src/cli.ts doctor

# Send a test message
bun run src/cli.ts send --to telegram:YOUR_CHAT_ID --message "Hello!"
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `pi-gw gateway` | Start the gateway |
| `pi-gw doctor` | Health check |
| `pi-gw send` | Send a message |
| `pi-gw config show` | Show current config |
| `pi-gw onboard` | Interactive setup wizard |

## Send Command Targets

```
telegram:<chatId>                           # DM to chat
telegram:<accountId>:<chatId>               # Specific account
telegram:<accountId>:<chatId>:topic:<tid>   # Topic in group
discord:<channelId>                         # Discord channel
```

## Common Issues

### "Cannot connect to Telegram"

1. **Verify bot token**:
   ```bash
   curl https://api.telegram.org/bot<TOKEN>/getMe
   ```
   Should return `{"ok":true,"result":{...}}`

2. **Check environment variable**:
   ```bash
   echo $TELEGRAM_BOT_TOKEN
   ```

3. **Ensure bot is not blocked**:
   - Check BotFather settings
   - Disable privacy mode for group chats

### "RPC pool exhausted"

This means all agent processes are busy. Increase pool size:

```jsonc
{
  "agent": {
    "pool": {
      "min": 2,
      "max": 8
    }
  }
}
```

### "Model rate limited"

Configure model failover chain:

```jsonc
{
  "agent": {
    "modelFailover": {
      "primary": "claude-sonnet-4",
      "fallbacks": ["gpt-4o", "gemini-pro"],
      "maxRetries": 2,
      "cooldownMs": 60000
    }
  }
}
```

### "Session not found"

This happens when the session key doesn't match. Check:

1. Correct channel format (`telegram:123456789`)
2. Account ID is correct for multi-account setups
3. Topic ID for Telegram groups with topics

### "WebSocket connection failed"

1. Check gateway is running: `bun run src/cli.ts doctor`
2. Verify port is not blocked by firewall
3. Use `wss://` for HTTPS (not `ws://`)

### "Authentication failed"

For WebChat or admin API:

1. Check `gateway.auth.token` in config
2. Use correct Authorization header: `Bearer <token>`
3. For development, set `auth.mode: "off"` (not recommended for production)

## Next Steps

- [Configuration](/en/configuration) — Configure channels, agents, and plugins
- [Telegram Channel](/en/telegram) — Set up Telegram bot
- [Discord Channel](/en/discord) — Set up Discord bot
- [WebChat](/en/webchat) — Use the built-in web chat
- [Plugin System](/en/plugins) — Extend with custom hooks

## Need Help?

- [Open an issue](https://github.com/openclaw/pi-gateway/issues)
- Check [discussions](https://github.com/openclaw/pi-gateway/discussions)
- Read the [FAQ](https://github.com/openclaw/pi-gateway/wiki/FAQ)