196 lines
6.2 KiB
Markdown
196 lines
6.2 KiB
Markdown
# 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.
|