Skip to content

OpenClaw On Truenas Scale Complete Setup Guide

github-actions[bot] edited this page Nov 20, 2026 · 4 revisions

Self-hosted AI agent framework with multi-provider LLM routing, homelab integration, and cybersecurity workflows

Part of the ULTIMATE CYBERSECURITY MASTER GUIDE

Version context: This is a tested deployment snapshot using OpenClaw 2026.4.15 and TrueNAS SCALE 25.04, not a current-version recommendation. Provider names, model IDs, app menus, and commands can change. Check current OpenClaw releases and vendor documentation before applying the steps.

OpenClaw tested snapshot 2026.4.15 TrueNAS SCALE Providers License


๐ŸŽฏ Purpose

Complete installation and configuration guide for deploying OpenClaw (a self-hosted, multi-provider AI agent framework) on TrueNAS SCALE, including known TrueNAS-Community-app-specific bugs and their workarounds. First of three companion OpenClaw guides - see use_cases.md for prompt examples and agent_skill_config.md for ready-to-apply agent personas once this install is complete.

โš™๏ธ Function

Eight parts covering app-catalog installation, the provider onboarding wizard (Anthropic/Gemini/Groq/Ollama), manual config fixes for wizard bugs (Groq model registration, Ollama API key), security hardening, NPMplus HTTPS reverse-proxy setup with local DNS override, and device pairing - followed by a troubleshooting section documenting specific failure modes and their exact fixes.

๐Ÿ† Goal

Get OpenClaw running on TrueNAS SCALE with all four LLM providers verified working, HTTPS access configured via NPMplus, and a paired device connected to the dashboard.

๐Ÿ“‹ When To Use

  • First-time OpenClaw deployment on TrueNAS SCALE
  • Diagnosing a specific OpenClaw/TrueNAS app failure (config service exit 1, WebSocket disconnects, provider not showing in models list) - check Troubleshooting first

What Is OpenClaw?

OpenClaw is a free, open-source AI agent framework that runs on your own hardware. Think of it as a personal AI assistant - like having a local version of ChatGPT that you control completely, connected to your messaging apps, files, and services.

What it can do:

  • Chat via Telegram, Discord, WhatsApp, Slack, Signal, and 50+ other platforms from a single agent
  • Read and write files, run shell commands, browse the web, and manage your calendar
  • Connect to multiple AI providers simultaneously (Anthropic, Google, Groq, local Ollama models) and route tasks to the best/cheapest model automatically
  • Remember context across sessions and schedule automated tasks with cron jobs
  • Extend functionality with community-built skills (ClawHub) for homelab management, GitHub, Notion, media servers, and more
  • Run 100% locally with Ollama - no data leaves your network

Why self-host it?

  • Your conversations stay on your hardware
  • Use free tiers of Groq and Gemini for most tasks, reserving paid APIs (like Claude) for complex work
  • Integrate with your existing homelab infrastructure
  • Full control over models, tools, and data

Companion Documents

This repository includes three guides. Start here, then refer to the others once setup is complete:

File Description
README.md (this file) Full installation and configuration guide for TrueNAS SCALE
use_cases.md Real-world example prompts organized by workflow - personal, IT support, blue team, red team, purple team, OSINT, and more
agent_skill_config.md Pre-built agent personas, skill configurations, cron jobs, and automation setups ready to apply to your instance

Table Of Contents


Prerequisites

  • TrueNAS SCALE 25.04+
  • NPMplus installed and running (for HTTPS reverse proxy)
  • OPNsense or similar router
  • A DuckDNS (or other DDNS) domain pointed at your public IP
  • Ollama running somewhere on your network (optional, for local inference)
  • API keys for: Anthropic, Groq, Google Gemini (all have free tiers)

Part 1: Install OpenClaw From App Catalog

1.1 Find The App

Go to Apps โ†’ Discover in the TrueNAS UI and search for OpenClaw (Community train).

1.2 Generate A Gateway Token

Before installing, generate a strong random token:

openssl rand -hex 32

Save this token - you'll need it throughout setup and to connect to the dashboard.

1.3 Configuration Settings

Fill in the app installer form as follows:

OpenClaw Configuration:

Field Value
Authentication Mode Shared bearer token (recommended)
Gateway Token (your generated token)
Proxy Trusted Proxies Your TrueNAS/NPMplus IP (e.g. 10.0.1.149)

Network Configuration:

Field Value
Port Bind Mode Publish port on the host for access through a trusted LAN or HTTPS reverse proxy only; do not forward this port directly to the public internet
Port Number 30262
Host Network Unchecked

User and Group Configuration:

Field Value
User ID 568
Group ID 568

Storage Configuration:

โš ๏ธ CRITICAL: Leave storage type as ixVolume - do NOT change to Host Path.

There is a known bug in OpenClaw 2026.3.2+ where the config init container fails when using Host Path storage. The ixVolume option (TrueNAS managed storage) is the only storage type that works reliably with the TrueNAS Community app.

Resources Configuration:

Field Value
CPUs 4
Memory (MB) 6144

1.4 Add Environment Variables

In the Additional Environment Variables section, add all provider API keys before installing:

Name Value
ANTHROPIC_API_KEY sk-ant-...
GROQ_API_KEY gsk_...
GEMINI_API_KEY AIza...
OLLAMA_API_KEY ollama-local
OLLAMA_BASE_URL http://YOUR_OLLAMA_IP:11434

Note: Use OLLAMA_BASE_URL - not OLLAMA_HOST. The OLLAMA_HOST variable is ignored by this version of OpenClaw.

Click Install and wait for the app to show as Running (green) in Apps โ†’ Installed.


Part 2: Run The Setup Wizard

2.1 Anthropic

sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice anthropic

At each prompt:

  • Security disclaimer โ†’ Yes
  • Setup mode โ†’ QuickStart
  • Config handling โ†’ Use existing values
  • Channel setup โ†’ Skip for now

2.2 Google Gemini

sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice google

At each prompt:

  • Security disclaimer โ†’ Yes
  • Setup mode โ†’ QuickStart
  • Config handling โ†’ Use existing values
  • Use existing GEMINI_API_KEY โ†’ Yes
  • Web search provider โ†’ Gemini (Google Search)
  • Channel setup โ†’ Skip for now

2.3 Groq

sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice groq

At each prompt:

  • Security disclaimer โ†’ Yes
  • Setup mode โ†’ QuickStart
  • Config handling โ†’ Use existing values
  • Channel setup โ†’ Skip for now

Note: The Groq wizard often completes without actually registering Groq models. If models list doesn't show Groq afterward, the manual fix in Part 3 is required.

2.4 Ollama

sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice ollama

At each prompt:

  • Security disclaimer โ†’ Yes
  • Setup mode โ†’ QuickStart
  • Config handling โ†’ Use existing values
  • Ollama mode โ†’ Local only
  • Ollama base URL โ†’ http://YOUR_OLLAMA_IP:11434 (no /v1 suffix)
  • Select a model from the discovered list
  • Channel setup โ†’ Skip for now

Part 3: Configure AI Providers

3.1 Fix Groq (Manual Config Edit)

The Groq wizard often completes without registering models. Fix this by editing the config file directly on the TrueNAS host:

sudo python3 -c "
import json
path = '/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json'
with open(path) as f:
    config = json.load(f)

config['auth']['profiles']['groq:default'] = {'provider': 'groq', 'mode': 'api_key'}
config['plugins']['entries']['groq'] = {'enabled': True}
config['agents']['defaults']['models']['groq/llama-3.3-70b-versatile'] = {}

with open(path, 'w') as f:
    json.dump(config, f, indent=2)
print('Done')
"

Validate the JSON:

sudo python3 -c "import json; json.load(open('/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json')); print('Valid')"

โš ๏ธ Important: Never use config set to add nested provider objects like models.providers.groq. OpenClaw's schema validator rejects partial provider entries written one field at a time. Always use the Python direct-edit method above for provider configuration.

3.2 Fix Ollama API Key

The Ollama wizard sets the API key to the literal string "OLLAMA_API_KEY" instead of resolving the value. Fix it:

sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set models.providers.ollama.apiKey "ollama-local"

3.3 Add Ollama Models To Allowlist

Check what models you have available:

curl -s http://YOUR_OLLAMA_IP:11434/api/tags

Then add your models to the agents allowlist:

sudo python3 -c "
import json
path = '/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json'
with open(path) as f:
    config = json.load(f)

# Replace with your actual model name from the api/tags output
config['agents']['defaults']['models']['ollama/YOUR_MODEL_NAME:latest'] = {}

with open(path, 'w') as f:
    json.dump(config, f, indent=2)
print('Done')
"

Part 4: Verify All Providers

Restart the app from the TrueNAS UI (Stop โ†’ Start), then verify:

sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs models list

Expected output:

Model                                      Input      Ctx      Local Auth  Tags
google/gemini-3.1-pro-preview              text+image 1024k    no    yes   default,configured
anthropic/claude-opus-4-7                  text+image 977k     no    yes   configured
anthropic/claude-haiku-4-5                 text+image 195k     no    yes   configured
ollama/YOUR_MODEL:latest                   text       8k       no    yes   configured
groq/llama-3.3-70b-versatile               text       128k     no    yes   configured

All four providers should be listed. If any are missing, revisit the relevant section in Part 3.


Part 5: Set Default Model & Tools Profile

Set Groq as the default model to minimize API costs:

sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set agents.defaults.model.primary "groq/llama-3.3-70b-versatile"

Set the tools profile. Valid values are minimal, coding, messaging, or full:

sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set tools.profile minimal
# Keep the minimal profile unless a specific task requires additional tools; enable only the narrow capabilities needed.

Part 6: Security Hardening

Run the built-in security audit:

sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs security audit

Fix the flagged issues:

# Add rate limiting against brute force attacks
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set gateway.auth.rateLimit '{"maxAttempts":10,"windowMs":60000,"lockoutMs":300000}'

# Lock down allowed origins to your HTTPS domain and local IP
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set gateway.controlUi.allowedOrigins '["https://openclaw.yourdomain.duckdns.org"]'

Restart the app from the TrueNAS UI to apply changes.


Part 7: Npmplus Reverse Proxy With HTTPS

7.1 Create A Proxy Host

In the NPMplus UI go to Hosts โ†’ Proxy Hosts โ†’ Add Proxy Host.

Details tab:

Field Value
Domain Name openclaw.yourdomain.duckdns.org
Scheme http
Forward Hostname/IP Your TrueNAS IP
Forward Port 30262

Keep this backend port blocked from direct public internet access; allow access only from the trusted reverse proxy or an explicitly trusted LAN.

Click the gear icon โš™๏ธ next to Forward Port and paste this into the advanced config box:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
more_clear_headers Alt-Svc;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_connect_timeout 60s;

โš ๏ธ The proxy_http_version 1.1 line is critical. WebSockets require HTTP/1.1 and will fail silently with HTTP/2 or HTTP/3.

TLS tab:

Field Value
TLS Certificate Request a new Certificate
Force HTTPS โœ… Enabled
HTTP/2 Support โŒ Disabled
HTTP/3 Support โŒ Disabled
Use DNS Challenge โœ… Enabled (required for DuckDNS)

Enable Use DNS Challenge and enter your DuckDNS token from https://www.duckdns.org.

7.2 Local DNS Override (Opnsense Unbound)

To access the HTTPS domain locally without hairpin NAT issues, add a host override in OPNsense:

Go to Services โ†’ Unbound DNS โ†’ Host Overrides โ†’ + and add:

Field Value
Host openclaw
Domain yourdomain.duckdns.org
Type A (IPv4 address)
IP address Your TrueNAS IP (e.g. 10.0.1.149)

Save and apply Unbound. Verify:

nslookup openclaw.yourdomain.duckdns.org YOUR_OPNSENSE_IP

Should return your TrueNAS LAN IP, not your public WAN IP. Add overrides for all your other NPMplus proxy hosts using the same pattern.

7.3 Port Forwarding

Forward external ports 80 and 443 from your router WAN to NPMplus on your TrueNAS. Confirm NPMplus port mappings:

sudo docker ps | grep npmplus

Part 8: Device Pairing

8.1 Access The Web Ui

Open https://openclaw.yourdomain.duckdns.org in your browser.

8.2 Connect To The Gateway

On the Gateway Dashboard enter:

  • WebSocket URL: wss://openclaw.yourdomain.duckdns.org
  • Gateway Token: (your token from Part 1)

Click Connect. The dashboard will show "pairing required".

8.3 Approve The Pairing Request

# List pending pairing requests
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs devices list

# Approve using the Request UUID from the output
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs devices approve YOUR-REQUEST-UUID

You are now connected to the OpenClaw dashboard.


Local Access Before HTTPS

Keep the dashboard bound to loopback or a trusted LAN while configuring HTTPS. Do not enable Chromeโ€™s insecure-origin override or place the gateway token in an HTTP URL. Use the HTTPS reverse proxy after certificate and origin checks are configured; if HTTPS is unavailable, access only through a trusted local tunnel and keep the token in the appโ€™s supported secure configuration.


Troubleshooting

App Fails To Start: config service exit 1

This is a known bug in OpenClaw 2026.3.2+ triggered by Host Path storage.

Fix: Delete the app and reinstall using ixVolume storage (the default). Do not change the storage type to Host Path.

App Fails To Start After Editing Config File

The config file has invalid JSON or failed schema validation.

Fix: Restore from the automatic backup OpenClaw creates before every edit:

# Find the config file
sudo find /mnt/.ix-apps -name "openclaw.json" 2>/dev/null

# Restore from backup
sudo cp /mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json.bak \
        /mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json

# Validate
sudo python3 -c "import json; json.load(open('/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json')); print('Valid')"

Then start the app from the TrueNAS UI.

config set Fails With Schema Validation Error

OpenClaw requires all fields of a provider entry to be present simultaneously. Setting nested provider objects one field at a time always fails validation.

Fix: Use the Python direct-edit method from Part 3.

Ollama Shows "Could Not Be Reached At 127.0.0.1:11434"

The OLLAMA_HOST environment variable is not supported by this version.

Fix: In the TrueNAS app environment variables, use OLLAMA_BASE_URL instead of OLLAMA_HOST.

Websocket Disconnected (1006) Through Npmplus

HTTP/2 or HTTP/3 is being negotiated, which breaks WebSocket upgrades.

Fix: Ensure proxy_http_version 1.1 is in the NPMplus advanced config, and that HTTP/2 and HTTP/3 are disabled in the TLS tab. Also ensure your Unbound DNS override is resolving the domain to your local TrueNAS IP - if the domain resolves to your WAN IP, traffic hairpins through NAT and the connection fails.

Certificate Request Fails With Internal Error In Npmplus

Port 80 is not accessible from the internet for the HTTP-01 ACME challenge.

Fix: Use the DNS Challenge option in NPMplus TLS settings with your DuckDNS token.

devices list Fails With Gateway Closed (1006)

The gateway process isn't running inside the container.

Fix:

sudo docker exec -d ix-openclaw-openclaw-1 node /app/openclaw.mjs gateway run

Wait a few seconds then retry devices list.


Reference: Key Commands

# Check running containers
sudo docker ps | grep openclaw

# View all configured models
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs models list

# Get a config value
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config get gateway.port

# Set a simple config value
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs config set KEY VALUE

# Run security audit
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs security audit

# List paired devices
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs devices list

# Approve a device pairing
sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs devices approve UUID

# View raw config file
sudo cat /mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json

# Validate config JSON
sudo python3 -c "import json; json.load(open('/mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json')); print('Valid')"

# Restore config from backup
sudo cp /mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json.bak \
        /mnt/.ix-apps/app_mounts/openclaw/config/.openclaw/openclaw.json

# View app lifecycle logs
sudo grep openclaw /var/log/app_lifecycle.log | tail -n 20

# Check environment variables in container
sudo docker exec -it ix-openclaw-openclaw-1 env | grep -E "GROQ|GEMINI|OLLAMA|ANTHROPIC"

# View container logs
sudo docker logs ix-openclaw-openclaw-1 2>&1 | tail -n 30

Cost Optimization

Provider Cost Best For
Groq Free tier (generous) Default for most tasks - fast Llama 3.3 70B
Google Gemini Free tier Long context tasks (1M token window)
Ollama (local) Free forever Sensitive tasks, offline use
Anthropic (Claude) Paid Complex reasoning, long documents

The Adaptive model mode in the dashboard automatically routes to a stronger model only when the task requires it, keeping costs minimal.


Operational Engineering & Safe Integration Path

After basic installation, treat this Gateway as a tool-using production application, not only a chat interface. Use these independent procedures before connecting sensitive accounts or enabling automatic actions:

Next Capability Practical Guide Gate Before Enabling
Durable notes and session recovery Context Engineering ยท Notes & Hooks Approved project records load correctly; stale context is detected
Tool/MCP integrations MCP & Permissions Server identity, scopes, tenant ACLs and denied-call tests
Agent workflows Orchestration ยท Reliability One owner for each write, idempotency, bounded retries and rollback
Model/provider routing Model Routing & Cost Privacy-compliant fallback and measured quality/cost
Alert or ticket automation Security Operations Synthetic events, authenticated ingress and human review
Security hardening Agent Threat Model Least privilege, secrets isolation and prompt-injection tests
Operations & evaluation Observability ยท Evaluations Sanitized traces, real test results, release approval

The OpenClaw guides contain historical, environment-specific commands. Inspect your installed version and official CLI/configuration schema before applying them; a successful JSON parse alone cannot prove a configuration is supported. Neither OpenClaw nor a local Ollama backend automatically ensures that every tool, logger or fallback is offline.

Next Steps

  • Set up Telegram for mobile access from anywhere:
    sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs onboard --auth-choice telegram
  • Install the TrueNAS skill from ClawHub to manage your homelab via OpenClaw
  • Rotate your API keys - Groq and Gemini keys were visible in shell history during initial setup
  • Run periodic health checks:
    sudo docker exec -it ix-openclaw-openclaw-1 node /app/openclaw.mjs security audit

Tested deployment snapshot: TrueNAS SCALE 25.04 ยท Dell R630 ยท OPNsense ยท NPMplus ยท Ollama ยท OpenClaw 2026.4.15

Related Files


๐Ÿ“„ Source: AI/OpenClaw/README.md | โœ๏ธ Suggest an edit | โฌ…๏ธ Back to Artificial Intelligence

Clone this wiki locally