vault backup: 2026-02-14 13:31:12
This commit is contained in:
Vincent Verbruggen
195
Personal/Areas/Servers/TrueNAS/OpenClaw.md
Normal file
195
Personal/Areas/Servers/TrueNAS/OpenClaw.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user