diff --git a/Personal/Areas/Servers/TrueNAS/OpenClaw.md b/Personal/Areas/Servers/TrueNAS/OpenClaw.md new file mode 100644 index 0000000..5699897 --- /dev/null +++ b/Personal/Areas/Servers/TrueNAS/OpenClaw.md @@ -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 +``` + +## 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://: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.