Vincent/Obsidian-Vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault backup: 2026-02-14 14:28:03

Browse Source
This commit is contained in:
Vincent Verbruggen
2026-02-14 14:28:03 +01:00
parent d3f97a1b6d
commit 3bd452ccca
1 changed files with 74 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
Personal/Areas/Servers/TrueNAS/OpenClaw.md
View File

@@ -26,10 +26,12 @@ 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
sudo chown -R 1000:1000 /mnt/tank/configs/openclaw/config
sudo chown -R 1000:1000 /mnt/tank/configs/openclaw/workspace
```
> **Important:** If you skip this step, onboarding will fail with `EACCES: permission denied` when writing `openclaw.json`.
## 2. Create the Telegram Bot
1. Open Telegram, search for `@BotFather`
@@ -43,6 +45,8 @@ In Dockge, create a new stack called `openclaw`.
### Compose YAML
Two services are required: `openclaw-gateway` runs the persistent gateway, and `openclaw-cli` is used for one-off CLI commands (onboarding, channel setup, diagnostics). The `cli` profile prevents it from starting automatically.
```yaml
services:
openclaw-gateway:
@@ -72,6 +76,10 @@ services:
- cli
```
> **Why two services?** The Docker image's default entrypoint runs `node openclaw.mjs gateway`. If you try to run CLI commands (like `onboard`) via the gateway service, it fails with `Cannot find module '/app/onboard'` because the entrypoint tries to execute the argument as a standalone script. The `openclaw-cli` service overrides `entrypoint` to `["node", "openclaw.mjs"]` so subcommands work correctly.
> **Why `--bind lan`?** The gateway defaults to binding on `127.0.0.1` (loopback) inside the container. Docker port mapping requires the process to listen on `0.0.0.0`, so `--bind lan` is mandatory for the port forwarding to work.
### Environment Variables
In the Dockge `.env` section, add:
@@ -87,12 +95,12 @@ 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
sudo 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`).
After onboarding completes, start the stack from the Dockge UI (or `sudo docker compose up -d openclaw-gateway`).
## 4. Configure OpenClaw
@@ -102,6 +110,12 @@ After the container is running, the config file lives at:
/mnt/tank/configs/openclaw/config/openclaw.json
```
The onboarding wizard writes this file. Key settings to verify:
- `gateway.bind` should be `"lan"` (not `"loopback"`)
- `gateway.auth.mode` should be `"token"` with a generated token
- `channels.telegram.enabled` should be `true`
### NanoGPT as Provider (OpenAI-compatible)
NanoGPT exposes an OpenAI-compatible API at `https://nano-gpt.com/api/v1`. Configure it as a custom provider:
@@ -148,27 +162,57 @@ 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"
sudo 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>
sudo docker compose run --rm openclaw-cli pairing approve telegram <CODE>
```
## 6. Verify
## 6. Access the Control UI
- 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 via SSH tunnel:
```bash
ssh -L 18789:localhost:18789 truenas_admin@<truenas-ip>
```
Then open `http://localhost:18789/` (must be localhost — the UI requires HTTPS or localhost)
The Control UI requires HTTPS or localhost (browser secure context requirement). Direct access via LAN IP will not work.
## 7. Security Considerations
### Step 1: SSH tunnel
```bash
ssh -L 18789:localhost:18789 truenas_admin@192.168.178.189
```
### Step 2: Get the dashboard URL with token
The gateway uses token-based authentication. The token is embedded in the URL fragment (`#token=...`). Get the full URL:
```bash
cd /mnt/tank/stacks/openclaw
sudo docker compose run --rm openclaw-cli dashboard --no-open
```
This prints a URL like:
```
http://172.16.10.3:18789/#token=your-gateway-token-here
```
### Step 3: Open in browser
Replace the IP with `localhost` and open:
```
http://localhost:18789/#token=your-gateway-token-here
```
> **Do not** access via `http://192.168.178.189:18789` directly — the gateway rejects non-localhost, non-HTTPS WebSocket connections with `code=4008 reason=connect failed`.
## 7. Verify
- Check gateway status: `sudo docker compose run --rm openclaw-cli gateway status`
- View logs: `sudo docker logs -f openclaw`
- Run diagnostics: `sudo docker compose run --rm openclaw-cli doctor`
## 8. 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.
@@ -182,19 +226,20 @@ 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 |
| `sudo docker compose run --rm openclaw-cli gateway status` | Check if gateway is running |
| `sudo docker compose restart openclaw-gateway` | Restart the gateway |
| `sudo docker compose run --rm openclaw-cli doctor` | Automated health checks |
| `sudo docker compose run --rm openclaw-cli dashboard --no-open` | Get Control UI URL with token |
| `sudo docker logs -f openclaw` | Stream live logs |
| `sudo docker compose run --rm openclaw-cli channels list` | List connected channels |
| `sudo docker compose pull && sudo 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.
- **`Cannot find module '/app/onboard'`**: You ran a CLI subcommand via the gateway service. Use `openclaw-cli` service instead (it has the correct entrypoint).
- **`EACCES: permission denied` on config files**: Host directories not owned by UID 1000. Run `sudo chown -R 1000:1000 /mnt/tank/configs/openclaw/config`.
- **`Bind: loopback` in doctor output**: The onboarding wizard set bind to loopback in the config file, overriding the `--bind lan` command flag. Edit `openclaw.json` and set `gateway.bind` to `"lan"`, then restart the gateway.
- **Browser shows "connection reset" or blank page**: You are accessing via LAN IP instead of localhost. Use the SSH tunnel and open `http://localhost:18789/#token=...`.
- **`code=4008 reason=connect failed` in logs**: The browser is connecting without the required token or via a non-secure origin. Get the full URL with `dashboard --no-open`.
- **Gateway Bridge errors**: Try `network_mode: host` in the compose file if bridge networking causes issues.
- **Container won't start**: Check `sudo docker logs openclaw` for config validation errors — OpenClaw rejects malformed JSON5.