# OpenClaw on TrueNAS SCALE

Self-hosted AI agent gateway that connects LLMs to messaging platforms (Telegram, Discord, WhatsApp). Runs as a persistent daemon — can message proactively, execute shell commands, manage files, and automate tasks.

- Previously known as: ClawdBot, MoltBot
- GitHub: https://github.com/openclaw/openclaw
- Docs: https://docs.openclaw.ai

## Prerequisites

- TrueNAS SCALE (24.10 Electric Eel or newer recommended — native Docker support)
- Dockge running on TrueNAS for Docker Compose management
- A dataset for OpenClaw storage: `tank/configs/openclaw`
- NanoGPT API key from https://nano-gpt.com (or OpenRouter key from https://openrouter.ai)
- Telegram bot token from @BotFather

## 1. Create Storage Datasets

In TrueNAS web UI, create two datasets under your apps pool:

```
tank/configs/openclaw/config    # maps to ~/.openclaw
tank/configs/openclaw/workspace # maps to ~/openclaw/workspace
```

Set permissions to UID 1000 (the container runs as `node` uid 1000):

```bash
chown -R 1000:1000 /mnt/tank/configs/openclaw/config
chown -R 1000:1000 /mnt/tank/configs/openclaw/workspace
```

## 2. Create the Telegram Bot

1. Open Telegram, search for `@BotFather`
2. Send `/newbot`
3. Choose a name and username (username must end in `bot`)
4. Save the bot token (format: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)

## 3. Deploy via Dockge

In Dockge, create a new stack called `openclaw`.

### Compose YAML

```yaml
services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - /mnt/tank/configs/openclaw/config:/home/node/.openclaw
      - /mnt/tank/configs/openclaw/workspace:/home/node/workspace
    environment:
      - NANO_GPT_API_KEY=${NANO_GPT_API_KEY}
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}

  openclaw-cli:
    image: ghcr.io/openclaw/openclaw:latest
    volumes:
      - /mnt/tank/configs/openclaw/config:/home/node/.openclaw
      - /mnt/tank/configs/openclaw/workspace:/home/node/workspace
    environment:
      - NANO_GPT_API_KEY=${NANO_GPT_API_KEY}
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
    entrypoint: ["node", "openclaw.mjs"]
    profiles:
      - cli
```

### Environment Variables

In the Dockge `.env` section, add:

```
NANO_GPT_API_KEY=your-nanogpt-key-here
OPENROUTER_API_KEY=your-openrouter-key-here
```

### First Run

Before starting the stack normally, run the onboarding wizard via SSH:

```bash
cd /mnt/tank/stacks/openclaw
docker compose run --rm openclaw-cli onboard --no-install-daemon
```

The `--no-install-daemon` flag is required in Docker since the gateway runs as a separate container, not as a system daemon.

After onboarding completes, start the stack from the Dockge UI (or `docker compose up -d openclaw-gateway`).

## 4. Configure OpenClaw

After the container is running, the config file lives at:

```
/mnt/tank/configs/openclaw/config/openclaw.json
```

### NanoGPT as Provider (OpenAI-compatible)

NanoGPT exposes an OpenAI-compatible API at `https://nano-gpt.com/api/v1`. Configure it as a custom provider:

```json5
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "nanogpt/claude-sonnet-4.5",
        "fallbacks": ["openrouter/anthropic/claude-sonnet-4.5"]
      }
    }
  },
  "env": {
    "NANO_GPT_API_KEY": "your-nanogpt-key",
    "OPENROUTER_API_KEY": "sk-or-your-openrouter-key"
  }
}
```

> **Note:** If NanoGPT is not natively supported as a provider, configure it as a custom provider with base URL `https://nano-gpt.com/api/v1`. Check the [custom providers docs](https://docs.openclaw.ai/gateway/configuration-reference#custom-providers-and-base-urls) for exact syntax.

### OpenRouter as Provider (alternative)

```json5
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.5"
      }
    }
  },
  "env": {
    "OPENROUTER_API_KEY": "sk-or-your-key"
  }
}
```

## 5. Connect Telegram

From SSH on TrueNAS, use the CLI service:

```bash
cd /mnt/tank/stacks/openclaw
docker compose run --rm openclaw-cli channels add --channel telegram --token "YOUR_BOT_TOKEN"
```

Then approve the pairing. Send a message to your bot in Telegram — it will reply with a pairing code. Approve it:

```bash
docker compose run --rm openclaw-cli pairing approve telegram <CODE>
```

## 6. Verify

- Check gateway status: `docker compose run --rm openclaw-cli gateway status`
- View logs: `docker logs -f openclaw`
- Run diagnostics: `docker compose run --rm openclaw-cli doctor`
- Access Control UI: `http://<truenas-ip>:18789/`

## 7. Security Considerations

- **Do not expose port 18789 to the public internet.** Use Tailscale, WireGuard, or VPN to access the Control UI remotely.
- Enable **explicit consent mode** to require approval before OpenClaw executes write/exec commands.
- Treat the `/mnt/tank/configs/openclaw/config` directory as sensitive — it contains API keys and session data.
- The container runs as non-root (uid 1000), which is good practice.
- Consider network isolation: create a dedicated Docker network or VLAN if your TrueNAS hosts other services.

## Useful Commands

All CLI commands below assume you are in `/mnt/tank/stacks/openclaw`.

| Command | Description |
|---------|-------------|
| `docker compose run --rm openclaw-cli gateway status` | Check if gateway is running |
| `docker compose restart openclaw-gateway` | Restart the gateway |
| `docker compose run --rm openclaw-cli doctor` | Automated health checks |
| `docker logs -f openclaw` | Stream live logs |
| `docker compose run --rm openclaw-cli channels list` | List connected channels |
| `docker compose pull && docker compose up -d openclaw-gateway` | Update to latest version |

## Troubleshooting

- **Gateway Bridge errors**: Common with Docker networking. Ensure the container can reach the internet. Try `host` network mode if bridge fails:
  ```yaml
  network_mode: host
  ```
- **Permission denied on volumes**: Verify UID 1000 owns the host directories.
- **OAuth/auth issues on headless setup**: Copy the redirect URL from the onboarding wizard and paste it back manually.
- **Container won't start**: Check `docker logs openclaw` for config validation errors — OpenClaw rejects malformed JSON5.