TetraHome/Tetra-AI-HA-App
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance documentation for OpenClaw Assistant add-on

Browse Source 
- Updated DOCS.md with a comprehensive architecture overview, installation steps, first-time setup guide, and configuration reference.
- Added detailed use case guides, including integration with Home Assistant's Assist pipeline and browser automation capabilities.
- Introduced SECURITY.md to outline security risks, best practices, and disclaimers associated with the add-on.
- Revised README.md to highlight key features and provide links to full documentation and security information.
This commit is contained in:
techartdev
2026-02-11 14:59:57 +02:00
parent fef38a2c56
commit 0865958385
3 changed files with 669 additions and 251 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOCS.md
+485 -214
View File
@@ -1,323 +1,594 @@
# OpenClaw Assistant (Home Assistant Add-on)
# OpenClaw Assistant — Home Assistant Add-on Documentation
This add-on runs **OpenClaw** inside **Home Assistant OS (HAOS)**.
This add-on runs [OpenClaw](https://github.com/openclaw/openclaw) inside Home Assistant OS (HAOS). It provides a fully self-contained environment with a web terminal, gateway server, and all the tools OpenClaw needs — no manual Docker setup required.
It’s designed to be friendly to non-technical users:
- The add-on provides a simple Home Assistant page (Ingress) with a terminal.
- You complete setup using OpenClaw’s built-in onboarding commands.
**Table of Contents**
1. [Architecture Overview](#1-architecture-overview)
2. [Installation](#2-installation)
3. [First-Time Setup](#3-first-time-setup)
4. [Accessing the Gateway Web UI](#4-accessing-the-gateway-web-ui)
5. [Configuration Reference](#5-configuration-reference)
6. [Use Case Guides](#6-use-case-guides)
7. [Data Persistence & Skills](#7-data-persistence--skills)
8. [Bundled Tools](#8-bundled-tools)
9. [Updating & Backup](#9-updating--backup)
10. [Troubleshooting](#10-troubleshooting)
11. [FAQ](#11-faq)
> **Important**: Before using this add-on, please read the [Security Risks & Disclaimer](SECURITY.md).
---
## 0) What is what? (quick explanation)
## 1. Architecture Overview
- **Ingress page** (inside Home Assistant): a landing page + terminal.
- **Gateway**: the OpenClaw server running inside the add-on container.
- **Gateway Web UI (Control UI)**: the web interface you open in your browser.
### What runs inside the add-on
The Gateway UI is opened in a **separate tab** (not embedded), because Home Assistant Ingress can have WebSocket issues.
The add-on container runs three services:
| Service | Port | Purpose |
|---|---|---|
| **OpenClaw Gateway** | 18789 (configurable) | The AI agent server — handles skills, chat, automations |
| **nginx** (Ingress proxy) | 8099 (fixed) | Serves the landing page inside Home Assistant |
| **ttyd** (Web terminal) | 7681 (configurable) | Provides a browser-based terminal for setup and management |
When you open the add-on page in Home Assistant, nginx serves a landing page with:
- An **Open Gateway Web UI** button (opens in a new tab to avoid WebSocket issues with Ingress)
- An embedded **terminal** for running commands
### Key directories
| Path | Persistent? | Contents |
|---|---|---|
| `/config/` | Yes | All user data — survives add-on updates and rebuilds |
| `/config/.openclaw/` | Yes | OpenClaw configuration (`openclaw.json`), skills, agent data |
| `/config/clawd/` | Yes | Agent workspace (ClawHub-installed skills, files) |
| `/config/.node_global/` | Yes | User-installed npm packages (skills installed via dashboard) |
| `/config/secrets/` | Yes | Tokens (e.g., `homeassistant.token`) |
| `/config/keys/` | Yes | SSH keys (e.g., router SSH key) |
| `/usr/lib/node_modules/openclaw/` | No | OpenClaw installation (rebuilt with each image update) |
> **Important**: Everything under `/config/` persists across add-on updates. The container filesystem (`/usr/`, `/opt/`, etc.) is rebuilt each time the image changes.
---
## 1) Install the add-on
## 2. Installation
1) Home Assistant → **Settings → Add-ons → Add-on store**
2) Add repository URL:
- Add-on store → ⋮ → **Repositories** → paste:
- `https://github.com/techartdev/OpenClawHomeAssistant`
3) Install **OpenClaw Assistant**
4) Start the add-on
1. In Home Assistant, go to **Settings → Add-ons → Add-on store**
2. Click ⋮ (top-right) → **Repositories** → paste one of:
- **Stable**: `https://github.com/techartdev/OpenClawHomeAssistant`
- **Dev/Experimental**: `https://github.com/techartdev/OpenClawHomeAssistant-dev`
3. Find and install **OpenClaw Assistant**
4. Click **Start**
**Supported architectures**: amd64, aarch64 (Raspberry Pi 4/5), armv7
---
## 2) First-time setup (step-by-step)
## 3. First-Time Setup
Open the add-on page (Ingress). You will see:
- **Open Gateway Web UI** button
- **Terminal** embedded on the page
### What happens on first boot
### Step A — Run OpenClaw onboarding
When the add-on starts for the first time, it automatically:
1. Creates persistent directories under `/config/`
2. Generates a minimal `openclaw.json` with a random gateway auth token
3. Syncs built-in skills to persistent storage
4. Starts the gateway, terminal, and nginx
### Step 1 — Run onboarding
Open the add-on page in Home Assistant. You'll see a landing page with an embedded terminal.
In the terminal, run:
- **Recommended**:
- `openclaw onboard`
```sh
openclaw onboard
```
If you prefer:
- `openclaw configure`
This interactive wizard walks you through connecting your AI providers (OpenAI, Google, Anthropic, etc.) and basic configuration.
Follow the prompts.
Alternatively, for more granular control:
### Step B — Get your Gateway token (needed for the Web UI)
```sh
openclaw configure
```
In the terminal run:
### Step 2 — Get your Gateway token
The gateway requires a token for authentication. To retrieve it:
```sh
openclaw config get gateway.auth.token
```
Copy the token somewhere safe.
Save this token — you'll need it to access the Gateway Web UI and for API integrations.
### Step C — Make the Gateway reachable from your browser
### Step 3 — Verify everything works
You have two common setups:
1. In the terminal, confirm the gateway is running:
```sh
openclaw gateway status
```
2. Click the **Open Gateway Web UI** button on the landing page
3. If prompted for a token, paste the one from Step 2 or go to the Overview tab, paste the token in the 'Gateway Token' field and press Connect.
#### Option 1: Use Home Assistant HTTPS (recommended)
If your Home Assistant is already exposed via HTTPS (Nabu Casa, reverse proxy, etc.), use that.
This avoids browser security issues.
---
#### Option 2: LAN access (http://192.168.x.x) — using add-on options (recommended)
The easiest way to enable LAN access is via the add-on configuration:
## 4. Accessing the Gateway Web UI
1. Go to Home Assistant → **Settings → Add-ons → OpenClaw Assistant → Configuration**
2. Set the following options:
- `gateway_bind_mode`: **lan** (enables LAN binding; use **loopback** for local-only access)
The Gateway Web UI (Control UI) is OpenClaw's main web interface. It opens in a **separate browser tab** because Home Assistant's Ingress proxy has WebSocket limitations.
### Setting up the "Open Gateway Web UI" button
Set `gateway_public_url` in the add-on configuration to the URL where the gateway is reachable from your browser.
**Examples**:
- LAN: `http://192.168.1.119:18789`
- Public HTTPS: `https://example.duckdns.org:12345`
The button opens: `<gateway_public_url>/?token=<your_token>`
### How to make the Gateway reachable
Choose the method that fits your setup:
#### Method A — HTTPS via reverse proxy (recommended)
If you use a reverse proxy (e.g., Nginx Proxy Manager, Caddy, Traefik, Cloudflare Tunnel), configure it to also forward the gateway port (default 18789) with HTTPS. This is the most secure option and avoids browser security warnings.
> **Note**: Nabu Casa remote access only proxies the Home Assistant UI (port 8123) — it cannot forward custom ports like 18789. The add-on's Ingress page (landing + terminal) works through Nabu Casa, but the Gateway Web UI requires a reverse proxy or LAN access.
#### Method B — LAN HTTP access (most common)
Enable LAN access via the add-on configuration:
1. Go to **Settings → Add-ons → OpenClaw Assistant → Configuration**
2. Set:
- `gateway_bind_mode`: **lan**
- `gateway_port`: **18789** (or your preferred port)
- `allow_insecure_auth`: **true** (required for HTTP access; see section 4 below)
- `allow_insecure_auth`: **true** (required for HTTP — see below)
- `gateway_public_url`: `http://<your-ha-ip>:18789`
3. Restart the add-on
The add-on will automatically update OpenClaw's configuration on startup.
#### Method C — SSH port forwarding (secure, no config changes)
#### Option 3: LAN access — manual configuration (advanced)
If you prefer to configure manually via terminal:
Forward the gateway port from your HA host to your local machine:
```sh
openclaw config set gateway.bind lan
openclaw config set gateway.port 18789
openclaw config set gateway.mode local
ssh -L 18789:127.0.0.1:18789 your-user@your-ha-ip
```
Then restart the add-on.
Then open `http://localhost:18789` in your browser. No need to change `gateway_bind_mode` or `allow_insecure_auth`.
---
### Browser security: "requires HTTPS or localhost"
## 3) Configure the “Open Gateway Web UI” button
The button uses the add-on option:
- `gateway_public_url`
Set it in Home Assistant → Add-on configuration.
Examples:
- LAN:
- `http://192.168.1.119:18789`
- Public HTTPS:
- `https://example.duckdns.org:12345`
The button will open:
`<gateway_public_url>/?token=<your_token>`
If the UI says **Unauthorized**, you likely used the wrong token. Re-check it with:
```sh
openclaw config get gateway.auth.token
```
---
## 4) Important: “requires HTTPS or localhost (secure context)”
Modern browsers sometimes refuse to run the Control UI on **plain HTTP** unless it is **localhost**.
If you open the Gateway UI over LAN HTTP and see:
Modern browsers block certain features on plain HTTP (non-localhost). If you see this error:
> control ui requires HTTPS or localhost (secure context)
You have 3 options:
**Solutions** (pick one):
- **Use HTTPS** (Method A above) — best long-term
- **Use SSH port forwarding** (Method C above) — `localhost` counts as secure
- **Enable `allow_insecure_auth`** — quick workaround for LAN HTTP access
### Option A — Use HTTPS (best)
Put the gateway behind HTTPS (recommended long-term).
### Unauthorized error
### Option B — Use localhost via port-forward
Access it as `http://localhost:18789` using SSH port forwarding from your computer.
If the Gateway UI shows **Unauthorized**, re-check your token:
### Option C — Allow insecure auth (quick workaround; less secure)
**Via add-on configuration (recommended)**:
1. Go to Home Assistant → **Settings → Add-ons → OpenClaw Assistant → Configuration**
2. Set `allow_insecure_auth`: **true**
3. Restart the add-on
**Via terminal (manual)**:
```sh
openclaw config set gateway.controlUi.allowInsecureAuth true
openclaw config get gateway.auth.token
```
Then restart the add-on.
This allows using the Control UI over LAN HTTP.
---
## 5) Add-on options (custom / HA-specific)
## 5. Configuration Reference
This add-on keeps options minimal but practical. See `openclaw_assistant_dev/config.yaml` for the full schema.
All options are set via **Settings → Apps/Add-ons → OpenClaw Assistant → Configuration** in Home Assistant. They are applied automatically on each add-on restart.
### Gateway Network Settings
Control how the OpenClaw gateway operates and binds to the network:
### General
- **`gateway_mode`** (string: **local** or **remote**, default **local**)
- **local**: Run the gateway locally in this add-on (recommended for most users)
- **remote**: Connect to a remote gateway running elsewhere
- This setting determines whether OpenClaw runs its own gateway or connects to an existing one
| Option | Type | Default | Description |
|---|---|---|---|
| `timezone` | string | `Europe/Sofia` | Timezone for the add-on (e.g., `America/New_York`, `Europe/London`) |
- **`gateway_bind_mode`** (string: **loopback** or **lan**, default **loopback**)
- **loopback**: Bind to 127.0.0.1 only — secure, local access only
- **lan**: Bind to all interfaces — accessible from your local network
- Only applies when `gateway_mode` is **local**
### Gateway
- **`gateway_port`** (int, default **18789**)
- Port number for the gateway to listen on
- Only applies when `gateway_mode` is **local**
- **`enable_openai_api`** (bool, default **false**)
- Enable the OpenAI-compatible Chat Completions endpoint (`/v1/chat/completions`)
- Required for integrating with HA Assist pipeline via [Extended OpenAI Conversation](https://github.com/jekalmin/extended_openai_conversation)
- See section 6 for full setup instructions
- **`allow_insecure_auth`** (bool, default **false**)
- Allow HTTP authentication for gateway access on LAN
- **WARNING**: Only enable if using HTTP (not HTTPS) for `gateway_public_url`
- Required for browser access over HTTP (see section 4)
These settings are applied automatically on add-on startup. No need to run `openclaw config` commands manually.
| Option | Type | Default | Description |
|---|---|---|---|
| `gateway_mode` | `local` / `remote` | `local` | **local**: run gateway in this add-on. **remote**: connect to an external gateway |
| `gateway_bind_mode` | `loopback` / `lan` | `loopback` | **loopback**: 127.0.0.1 only (secure). **lan**: all interfaces (LAN-accessible). Only applies when `gateway_mode` is `local` |
| `gateway_port` | int | `18789` | Port for the gateway. Only applies when `gateway_mode` is `local` |
| `gateway_public_url` | string | _(empty)_ | Public URL for the "Open Gateway Web UI" button. Example: `http://192.168.1.119:18789` |
| `enable_openai_api` | bool | `false` | Enable the OpenAI-compatible `/v1/chat/completions` endpoint. Required for [Assist pipeline integration](#6c-assist-pipeline-integration-openai-api) |
| `allow_insecure_auth` | bool | `false` | Allow HTTP (non-HTTPS) authentication on LAN. **Required** for browser access over plain HTTP |
### Terminal
- **`enable_terminal`** (bool, default **true**)
- Enable or disable the web terminal button inside Home Assistant
- **`terminal_port`** (int, default **7681**)
- Port number for the web terminal (ttyd) to listen on
- Change this if port 7681 conflicts with another service on your system
- Valid range: 1024-65535
Security note: the terminal gives shell access inside the add-on container.
| Option | Type | Default | Description |
|---|---|---|---|
| `enable_terminal` | bool | `true` | Show the web terminal on the add-on page |
| `terminal_port` | int | `7681` | Port for the terminal (ttyd). Change if 7681 conflicts. Range: 1024-65535 |
### Home Assistant token
- `homeassistant_token` (optional)
### Security & Tokens
If set, it is written to:
- `/config/secrets/homeassistant.token`
| Option | Type | Default | Description |
|---|---|---|---|
| `homeassistant_token` | string | _(empty)_ | Optional HA long-lived access token (use at own risk, can be very unsecure but very powerful). Saved to `/config/secrets/homeassistant.token` for use by scripts/skills |
### Router SSH (generic)
For custom automations that need SSH access to a router/firewall or other LAN device:
- `router_ssh_host`
- `router_ssh_user`
- `router_ssh_key_path` (default `/data/keys/router_ssh`)
### Router SSH
How to provide the key:
- Put the private key file under the add-on config directory so it appears in-container at `/data/keys/...`
- Recommended permissions: `chmod 600`
For skills or scripts that need SSH access to a router, firewall, or other network device:
### Session cleanup
- `clean_session_locks_on_start` (bool, default **true**) — Remove stale lock files on startup
- `clean_session_locks_on_exit` (bool, default **true**) — Remove stale lock files on shutdown
| Option | Type | Default | Description |
|---|---|---|---|
| `router_ssh_host` | string | _(empty)_ | Hostname or IP of the SSH target |
| `router_ssh_user` | string | _(empty)_ | SSH username |
| `router_ssh_key_path` | string | `/data/keys/router_ssh` | Path to the private key inside the container |
To provide the SSH key: place the private key file in the add-on config directory so it appears at the configured path inside the container. Set permissions: `chmod 600`. (use at own risk, can be very unsecure but very powerful)
### Maintenance
| Option | Type | Default | Description |
|---|---|---|---|
| `clean_session_locks_on_start` | bool | `true` | Remove stale session lock files on startup (safe — only removes locks when gateway isn't running) |
| `clean_session_locks_on_exit` | bool | `true` | Remove session lock files on clean shutdown |
---
## 6) Integrate with Home Assistant Assist Pipeline
## 6. Use Case Guides
OpenClaw's Gateway exposes an **OpenAI-compatible Chat Completions endpoint**. This means you can use OpenClaw as a **conversation agent** in Home Assistant's Assist pipeline — enabling voice control, automations, and smart home commands powered by OpenClaw.
### 6a. LAN Access Setup
### How it works
This is the most common setup — accessing the Gateway Web UI from a browser on your local network.
1. OpenClaw Gateway serves `POST /v1/chat/completions` (same port as the gateway)
2. [Extended OpenAI Conversation](https://github.com/jekalmin/extended_openai_conversation) (HACS integration) connects HA's Assist pipeline to any OpenAI-compatible endpoint
3. Both run on the same machine, so communication is via `127.0.0.1`
1. Go to **Settings → Add-ons → OpenClaw Assistant → Configuration**
2. Set these options:
### Step 1 — Enable the OpenAI API endpoint
| Option | Value |
|---|---|
| `gateway_bind_mode` | **lan** |
| `gateway_port` | **18789** |
| `allow_insecure_auth` | **true** |
| `gateway_public_url` | `http://<your-ha-ip>:18789` |
**Via add-on configuration (recommended)**:
1. Go to Home Assistant → **Settings → Add-ons → OpenClaw Assistant → Configuration**
2. Set `enable_openai_api`: **true**
3. Restart the add-on
4. Open the **Open Gateway Web UI** button — it should now work from any device on your LAN
**Security note**: `allow_insecure_auth` allows authentication over plain HTTP. This is fine on a trusted home network but should not be used over the internet. For public access, use HTTPS.
### 6b. Remote Gateway Mode
If you have an OpenClaw gateway running on a different machine (e.g., a more powerful server), you can configure this add-on to connect to it instead of running its own.
1. Set `gateway_mode`: **remote**
2. In the add-on terminal, configure the remote gateway URL:
```sh
openclaw config set gateway.url <remote-gateway-url>
```
3. Restart the add-on
**Via terminal (manual)**:
When `gateway_mode` is `remote`:
- The add-on does **not** start a local gateway process
- `gateway_bind_mode` and `gateway_port` are ignored
- The terminal and landing page still work normally
- You still need the remote gateway's auth token
### 6c. Assist Pipeline Integration (OpenAI API)
OpenClaw's Gateway exposes an **OpenAI-compatible Chat Completions endpoint** (`POST /v1/chat/completions`). This lets you use OpenClaw as a **conversation agent** in Home Assistant's Assist pipeline — enabling voice control, automations, and smart home commands.
#### Prerequisites
- [HACS](https://hacs.xyz/) installed on your Home Assistant
- [Extended OpenAI Conversation](https://github.com/jekalmin/extended_openai_conversation) integration
#### Step 1 — Enable the endpoint
In the add-on configuration, set `enable_openai_api`: **true**, then restart.
Or via terminal:
```sh
openclaw config set gateway.http.endpoints.chatCompletions.enabled true
```
### Step 2 — Install Extended OpenAI Conversation
#### Step 2 — Install Extended OpenAI Conversation
1. Install [HACS](https://hacs.xyz/) if you haven't already
2. In HACS, add **Extended OpenAI Conversation** as a custom repository:
1. In HACS, add as a custom repository:
- Repository: `https://github.com/jekalmin/extended_openai_conversation`
- Category: **Integration**
3. Install it and restart Home Assistant
2. Install and restart Home Assistant
### Step 3 — Get your Gateway token
#### Step 3 — Configure the integration
In the add-on terminal, run:
1. Go to **Settings → Devices & Services → Add Integration**
2. Search for **Extended OpenAI Conversation**
3. Configure:
- **API Key**: your gateway token (`openclaw config get gateway.auth.token`)
- **Base URL**: `http://127.0.0.1:18789/v1`
- **API Version**: leave empty
- **Organization**: leave empty
- **Skip Authentication**: **true**
> If using `gateway_bind_mode: lan`, you can also use `http://<your-ha-ip>:18789/v1` — this allows other HA instances on your network to connect too.
#### Step 4 — Set as conversation agent
1. Go to **Settings → Voice Assistants**
2. Edit your assistant (or create a new one)
3. Under **Conversation agent**, select **Extended OpenAI Conversation**
#### Step 5 — Expose entities
Go to **Settings → Voice Assistants → Expose** and toggle on the entities you want OpenClaw to control.
You can now use Assist (voice or text) and OpenClaw will handle conversations, control devices, answer questions, and create automations.
### 6d. Browser Automation (Chromium)
The add-on includes **Chromium** for browser-based automation tasks. OpenClaw can use it for web scraping, form filling, website testing, and other browser automation skills.
To enable it, add to `/config/.openclaw/openclaw.json`:
```json
{
"browser": {
"enabled": true,
"headless": true,
"noSandbox": true
}
}
```
> **Note**: `noSandbox` is required inside Docker containers due to security namespace restrictions.
### 6e. Router / Network Device SSH
If you have skills or scripts that need SSH access to a router, firewall, or other network device:
1. Generate an SSH key pair (if you don't have one):
```sh
ssh-keygen -t ed25519 -f /config/keys/router_ssh -N ""
```
2. Copy the public key to your router:
```sh
cat /config/keys/router_ssh.pub
```
Add it to the router's authorized keys.
3. Configure the add-on options:
- `router_ssh_host`: your router's IP (e.g., `192.168.1.1`)
- `router_ssh_user`: SSH username (e.g., `admin`)
- `router_ssh_key_path`: `/config/keys/router_ssh` (or wherever you saved it)
4. Test from the terminal:
```sh
ssh -i /config/keys/router_ssh admin@192.168.1.1
```
The connection details are also saved to `/config/CONNECTION_NOTES.txt` for reference by scripts.
---
## 7. Data Persistence & Skills
### What persists across add-on updates
| Data | Location | Persists? |
|---|---|---|
| OpenClaw config | `/config/.openclaw/openclaw.json` | Yes |
| Built-in skills | `/config/.openclaw/skills/` | Yes |
| Agent sessions & data | `/config/.openclaw/agents/` | Yes |
| ClawHub workspace | `/config/clawd/` | Yes |
| User-installed npm skills | `/config/.node_global/` | Yes |
| SSH keys | `/config/keys/` | Yes |
| Tokens | `/config/secrets/` | Yes |
| Homebrew-installed tools | `/home/linuxbrew/` | **No** — container filesystem |
| OpenClaw binary | `/usr/lib/node_modules/openclaw/` | **No** — reinstalled from image |
### How built-in skills work
OpenClaw ships with premade skills (e.g., web search, file management). On each startup, the add-on:
1. Copies built-in skills from the image to `/config/.openclaw/skills/`
2. Creates a symlink from the image path back to persistent storage
3. On subsequent boots, only newer files are synced (existing files are preserved)
This means built-in skills survive image rebuilds, and any customizations you make to skill files are preserved.
### How user-installed skills work
When you install a skill via the OpenClaw dashboard or `npm install -g`, the add-on redirects global npm installs to `/config/.node_global/`. This directory persists across updates.
The add-on also configures `pnpm` global directory to persistent storage at `/config/.node_global/pnpm/`.
### Homebrew-installed tools
Some skills depend on CLI tools installed via Homebrew (e.g., `gemini`, `aider`). These are installed into `/home/linuxbrew/` which is **not persistent** — they are lost on image rebuild. Skills will typically reinstall their dependencies automatically when needed.
---
## 8. Bundled Tools
The add-on image includes these tools, available in the terminal:
| Tool | Command | Notes |
|---|---|---|
| Git | `git` | Version control |
| Vim | `vim` | Text editor |
| Nano | `nano` | Text editor (beginner-friendly) |
| bat | `bat` (alias for `batcat`) | Syntax-highlighted `cat` |
| fd | `fd` (alias for `fdfind`) | Fast file finder |
| ripgrep | `rg` | Fast text search |
| curl | `curl` | HTTP client |
| jq | `jq` | JSON processor |
| Python 3 | `python3` | Scripting |
| Node.js 22 | `node` | JavaScript runtime |
| npm | `npm` | Node package manager |
| pnpm | `pnpm` | Fast Node package manager |
| Homebrew | `brew` | Package manager (optional — may not be available on all CPUs) |
| Chromium | `chromium` | Headless browser for automation |
| SSH | `ssh` | Remote access |
---
## 9. Updating & Backup
### Updating the add-on
Home Assistant checks for add-on updates automatically. When an update is available:
1. Go to **Settings → Add-ons → OpenClaw Assistant**
2. Click **Update**
3. The add-on will rebuild with the new image
**What happens during an update**:
- The container is destroyed and recreated from the new image
- Everything under `/config/` is preserved (config, skills, workspace, keys)
- Homebrew packages are lost (reinstalled by skills on demand)
- The OpenClaw binary is updated to the version in the new image
### Checking your version
The add-on version is shown on the add-on page in Home Assistant. To check the OpenClaw version:
```sh
openclaw --version
```
### Backup
Home Assistant's built-in backup system automatically includes add-on configuration data (`/config/`). This covers all persistent data: OpenClaw config, skills, workspace, keys, and tokens.
**To create a backup**: Go to **Settings → System → Backups → Create Backup**
**Manual backup** (from the terminal):
```sh
# Key paths to back up:
# /config/.openclaw/ - OpenClaw config, skills, agent data
# /config/clawd/ - ClawHub workspace
# /config/.node_global/ - User-installed npm skills
# /config/keys/ - SSH keys
# /config/secrets/ - Tokens
```
### Factory reset
To reset the add-on to a clean state, remove the persistent data:
```sh
rm -rf /config/.openclaw /config/clawd /config/.node_global
```
Then restart the add-on. It will re-bootstrap a fresh configuration.
> **Warning**: This deletes all your OpenClaw configuration, skills, and workspace data. Back up first if needed.
---
## 10. Troubleshooting
### How to read add-on logs
Go to **Settings → Add-ons → OpenClaw Assistant → Log** tab. Logs show startup messages, errors, and service status.
### Port 8099 conflict (add-on page won't load)
**Symptom**: `bind() to 0.0.0.0:8099 failed (98: Address already in use)` in logs.
**Cause**: A stale nginx process from a previous run is still holding the port. This can happen after a crash or unclean restart.
**Fix**: Restart the add-on. The startup script automatically cleans up stale processes. If the problem persists, stop the add-on, wait 10 seconds, then start it again.
### Port 7681 conflict (terminal won't load)
**Symptom**: `lws_socket_bind: ERROR on binding fd to port 7681` in logs.
**Fix**: Either restart the add-on (stale process cleanup), or change `terminal_port` to a different value (e.g., `7682`).
### ERR_CONNECTION_REFUSED
**Symptom**: Browser shows connection refused when opening the Gateway Web UI.
**Checks**:
1. Is the gateway running? In the terminal: `openclaw gateway status`
2. Is the bind mode correct? `openclaw config get gateway.bind` — must be `lan` for LAN access
3. Is the port correct? `openclaw config get gateway.port`
4. Is the firewall blocking the port? Check your HA host firewall rules
### Gateway UI shows "Unauthorized"
**Fix**: Get the correct token and use it:
```sh
openclaw config get gateway.auth.token
```
Copy the token — you'll need it as the API key.
Paste this token when the UI prompts for authentication, or append it to the URL: `http://<ip>:18789/?token=<your-token>`
### Step 4 — Configure Extended OpenAI Conversation
### Terminal not visible
1. Go to **Settings → Devices & Services → Add Integration**
2. Search for **Extended OpenAI Conversation**
3. Configure:
- **API Key**: Paste your gateway token
- **Base URL**: `http://127.0.0.1:18789/v1` or a LAN url if you use `gateway_bind_mode: lan`
- **API Version**: leave empty
- **Organization**: leave empty
- **Skip Authentication**: **true**
1. Check that `enable_terminal` is **true** in the add-on configuration
2. Check logs for `Starting web terminal (ttyd)` — if missing, the terminal is disabled
3. If you see a port conflict error, change `terminal_port` to a different value
### Step 5 — Set as Conversation Agent
### Skills disappearing after update
1. Go to **Settings → Voice Assistants**
2. Edit your assistant (default: "Home Assistant")
3. Under **Conversation agent**, select **Extended OpenAI Conversation**
Built-in skills are synced to persistent storage on each startup. If skills are missing:
### Step 6 — Expose entities
1. Check logs for `INFO: Synced built-in skills to persistent storage` — this confirms the sync ran
2. If you see `WARN: Built-in skills directory not found`, the OpenClaw installation may be corrupted. Try reinstalling the add-on.
3. User-installed skills (via dashboard) are stored in `/config/.node_global/` and should survive updates
Expose the entities you want OpenClaw to control:
- Go to `http://{your-ha}/config/voice-assistants/expose`
- Toggle on the entities OpenClaw should be able to see and control
### Homebrew errors / CPU compatibility
### Done!
**Symptom**: `Homebrew's x86_64 support on Linux requires a CPU with SSSE3 support!`
You can now use Assist (voice or text) and OpenClaw will handle the conversation. It can:
- Control your smart home devices
- Answer questions using its skills
- Create automations
- Query entity history
**Cause**: Your CPU doesn't support SSSE3 instructions (required by Homebrew). Affects older Intel Atom, Celeron, or pre-2006 processors.
**Tip**: If using LAN access (`gateway_bind_mode: lan`), other HA instances on your network can also connect to this endpoint.
**Impact**: Skills that depend on Homebrew-installed CLI tools (e.g., `gemini`, `aider`) won't work. Core OpenClaw functionality is unaffected.
**Workarounds**:
- Use a machine with a newer CPU (Intel Core 2 or newer, ~2006+)
- Install the required CLI tools manually if possible
- Use alternative skills that don't require Homebrew dependencies
### "openclaw: command not found"
The OpenClaw binary should be installed at `/usr/lib/node_modules/openclaw/`. If this error appears:
1. Check the add-on logs for npm installation errors during build
2. Try restarting the add-on
3. If the problem persists, uninstall and reinstall the add-on
### Gateway won't start / config errors
**Symptom**: `ERROR: Failed to apply gateway settings` in logs.
**Fix**: The `openclaw.json` config file may be corrupted. To reset it:
```sh
rm /config/.openclaw/openclaw.json
```
Restart the add-on — it will generate a fresh config. You'll need to run `openclaw onboard` again.
---
## Troubleshooting
## 11. FAQ
### Some skills fail to install (Homebrew errors)
**Does this work on Raspberry Pi?**
Yes. The add-on supports aarch64 (Raspberry Pi 4/5) and armv7 (Raspberry Pi 3). Note that Homebrew may not work on all ARM devices, but core functionality is unaffected.
If you see errors like:
- `Homebrew's x86_64 support on Linux requires a CPU with SSSE3 support!`
- `spawn brew ENOENT` or `brew: command not found`
**Can I run multiple agents?**
OpenClaw supports multiple agent profiles. Configure them via `openclaw configure` or by editing `/config/.openclaw/openclaw.json`. The gateway serves all configured agents.
**Cause**: Your CPU doesn't support SSSE3 instructions (required by Homebrew). This affects older CPUs like some Intel Atom, Celeron, or pre-2006 processors.
**Can I use a remote gateway?**
Yes. Set `gateway_mode` to `remote` and configure the remote gateway URL via `openclaw config set gateway.url <url>`. See [Remote Gateway Mode](#6b-remote-gateway-mode).
**Impact**: Skills that depend on CLI tools installed via Homebrew (e.g., `gemini`, `aider`) won't install. Core OpenClaw functionality still works.
**How do I change the AI model or provider?**
Run `openclaw configure` in the terminal to reconfigure your AI providers, or edit `/config/.openclaw/openclaw.json` directly. You can use OpenAI, Google (Gemini), Anthropic (Claude), local models, and more.
**Solutions**:
1. **Use a newer CPU** with SSSE3 support (Intel Core 2 or newer, ~2006+)
2. **Install dependencies manually** if you know which tools are needed
3. **Use alternative skills** that don't require Homebrew dependencies
**Can other devices on my network use the OpenClaw API?**
Yes, if you set `gateway_bind_mode` to `lan`. Any device on your network can connect to `http://<ha-ip>:18789`. Use the gateway token for authentication. This also enables the [Assist pipeline integration](#6c-assist-pipeline-integration-openai-api) from other HA instances.
The add-on will still start and work - Homebrew is optional.
### I get ERR_CONNECTION_REFUSED
- The gateway is not reachable at that IP/port.
- Confirm bind/port in terminal:
- `openclaw config get gateway.bind`
- `openclaw config get gateway.port`
### The Gateway UI opens but shows Unauthorized
- Fetch the token:
- `openclaw config get gateway.auth.token`
### Terminal isn’t visible
- Ensure `enable_terminal=true`
- Check logs for `Starting web terminal (ttyd)`
**Where is my data stored on the host?**
The add-on's `/config/` directory maps to `/addon_configs/<slug>/` on the Home Assistant host. This is included in HA backups automatically.
README.md
+16 -37
View File
@@ -6,27 +6,27 @@ This repository contains a Home Assistant add-on that runs **OpenClaw** inside *
> Upstream rename history (FYI): clawdbot → moltbot → **openclaw** (final).
## What you get
## Key Features
- An always-on OpenClaw gateway running as a Supervisor-managed add-on.
- A reliable **Ingress landing page** inside Home Assistant that includes:
- an embedded **web terminal** (ttyd)
- a button to open the **Gateway Web UI** in a **separate browser tab** (not embedded)
- Persistent state under the add-on config directory (in-container: `/config`).
- **AI Gateway** — OpenClaw server with chat, skills, and automation capabilities
- **Web Terminal** — browser-based terminal embedded in Home Assistant
- **Assist Pipeline** — use OpenClaw as a conversation agent via the OpenAI-compatible API
- **Browser Automation** — Chromium included for web scraping and automation skills
- **Persistent Storage** — skills, config, and workspace survive add-on updates
- **Bundled Tools** — git, vim, nano, bat, fd, ripgrep, curl, jq, python3, pnpm, Homebrew
## Why the Gateway UI is not embedded in Ingress
## Supported Architectures
The Gateway Web UI requires WebSockets that can be flaky through HA Ingress depending on proxying/mixed-content.
So we **don’t embed** it. Instead, the Ingress page gives you a button that opens the Gateway UI directly using
`gateway_public_url`.
| Architecture | Supported |
|---|---|
| amd64 | ✅ |
| aarch64 (RPi 4/5) | ✅ |
| armv7 (RPi 3) | ✅ |
## Security model (high level)
## Documentation
- The add-on **does not** manage or overwrite OpenClaw’s full config.
- OpenClaw is configured via its own interactive tools (`openclaw setup`, `openclaw onboard`, `openclaw configure`) using the terminal.
- On first boot only (when config is missing), the add-on bootstraps a minimal config to let the gateway start:
- `gateway.mode=local`
- `gateway.auth.mode=token` with a generated token
- **[Full documentation →](DOCS.md)** — installation, configuration, use cases, troubleshooting, and more
- **[Security Risks & Disclaimer →](SECURITY.md)** — important risks to understand before using this add-on
## Install
@@ -36,27 +36,6 @@ So we **don’t embed** it. Instead, the Ingress page gives you a button that op
- `https://github.com/techartdev/OpenClawHomeAssistant`
4. Install **OpenClaw Assistant**
## First run (recommended)
1. Open the add-on page (Ingress) and use the embedded terminal.
2. Run one of:
- `openclaw onboard`
- `openclaw configure`
3. (Optional, but recommended) Set **gateway_public_url** in add-on options.
- Then the Ingress page will show an "Open Gateway Web UI" button.
See **[DOCS.md](DOCS.md)** for a step-by-step first-time setup guide + troubleshooting.
## Add-on options (kept intentionally small)
See `openclaw_assistant/config.yaml` for the authoritative schema.
- `enable_terminal` (default: **true**) — enables the embedded web terminal.
- `gateway_public_url` — only used to build the external Gateway UI link.
- `timezone`
- `homeassistant_token` (optional) — written to `/config/secrets/homeassistant.token` for local scripts.
- `router_ssh_*` (optional) — SSH settings for a router/network device (custom automation).
## Support / Donations
If you find this useful and you want to bring me a coffee to make more useful things, or support the project, use the link below:
SECURITY.md
+168
View File
@@ -0,0 +1,168 @@
# Security Risks & Disclaimer
This document outlines the security risks associated with running the OpenClaw Assistant Home Assistant add-on and provides best practices for safe usage.
**By installing and using this add-on, you acknowledge and accept the risks described below.**
---
## Disclaimer
This add-on is provided **"AS IS"**, without warranty of any kind, under the [MIT License](LICENSE).
The authors and contributors of this add-on are **not responsible** for any damage, data loss, security breach, unauthorized access, financial loss, or any other harm that may occur as a result of installing, configuring, or using this add-on. This includes but is not limited to:
- Unintended actions performed by the AI agent
- Exposure of sensitive data (tokens, credentials, personal information)
- Unauthorized access to your Home Assistant instance or network
- Damage to smart home devices or connected systems
- Actions taken by third-party skills or integrations
**You use this add-on entirely at your own risk.**
---
## Understanding the Risks
### 1. Autonomous AI Agent
OpenClaw is an **agentic AI assistant** — it can plan, reason, and execute actions autonomously. Unlike a simple chatbot, it can:
- Execute shell commands on the add-on container
- Control smart home devices (if integrated with Assist pipeline or HA long-lived access token)
- Read and write files
- Make HTTP requests to external services
- Install and run third-party skills
**Risk**: If the agent is manipulated (e.g., via prompt injection from a malicious webpage or document), it could perform unintended actions within its permissions.
**Mitigation**: Review what entities you expose to the Assist pipeline. Only expose devices you're comfortable with the AI controlling.
### 2. Network Exposure
When `gateway_bind_mode` is set to `lan`, the gateway is accessible to **all devices on your local network**. When exposed to the internet (via port forwarding or reverse proxy), it becomes accessible to **anyone**.
**Risks**:
- Unauthorized users could interact with your AI agent
- API tokens could be intercepted over plain HTTP
- The gateway endpoint could be discovered by network scanners
**Mitigations**:
- Use HTTPS whenever possible (reverse proxy with TLS)
- Never expose the gateway port directly to the internet without authentication and encryption
- Use `gateway_bind_mode: loopback` if you only need local access
- Keep your gateway auth token secret
### 3. Plain HTTP Authentication (`allow_insecure_auth`)
Enabling `allow_insecure_auth` transmits authentication tokens over **unencrypted HTTP**. On a trusted home network this is generally acceptable, but:
**Risks**:
- Anyone on your network can intercept the token
- If your Wi-Fi is compromised, the token is exposed
- The token grants full access to the gateway
**Mitigations**:
- Only enable on trusted networks
- Never enable when the gateway is exposed to the internet
- Rotate your gateway token periodically: `openclaw config set gateway.auth.token <new-token>`
### 4. Home Assistant Token
The `homeassistant_token` option stores a **long-lived access token** that grants broad access to your Home Assistant instance. This is extremely powerful — it can control devices, read state, trigger automations, and more.
**Risks**:
- If the container is compromised, the attacker gains full HA access
- Skills or scripts running inside the add-on have access to this token
- The token does not expire unless manually revoked
**Mitigations**:
- Only provide this token if skills specifically require it
- Create a dedicated HA user with limited permissions for this token
- Revoke and regenerate the token if you suspect compromise
- Monitor your HA logs for unexpected API activity
### 5. Third-Party Skills & Supply Chain
OpenClaw supports installing skills from the community (ClawHub) and via npm. These are **third-party code** running inside the add-on container.
**Risks**:
- Malicious skills could exfiltrate data, install backdoors, or perform harmful actions
- Skills have access to the same permissions as the OpenClaw process
- Compromised npm packages could affect your installation
- [Security researchers have already found malicious skills](https://thehackernews.com/2026/02/researchers-find-341-malicious-clawhub.html) published to ClawHub
**Mitigations**:
- Only install skills from trusted sources
- Review skill code before installing when possible
- Monitor the add-on logs for unexpected activity
- Keep the add-on updated to get security patches
### 6. Router SSH Access
The `router_ssh_*` options allow the add-on to SSH into your router or network devices. This grants **direct access to your network infrastructure**.
**Risks**:
- A compromised add-on could reconfigure your router
- Firewall rules could be modified
- Network traffic could be intercepted or redirected
**Mitigations**:
- Use a dedicated SSH key with minimal permissions
- Restrict the SSH user's capabilities on the router (read-only if possible)
- Only enable if you have a specific use case that requires it, and only if you understand the risks very well
### 7. Browser Automation (Chromium)
The bundled Chromium runs with `noSandbox` (required in Docker). This reduces browser-level security isolation.
**Risks**:
- A malicious webpage could potentially escape the browser sandbox
- Automated browsing could expose session cookies or credentials
- Browser automation skills could visit unintended websites
**Mitigations**:
- Only use browser automation with trusted skills
- Do not use it to log into sensitive accounts
- The container itself provides some isolation from the host
### 8. Prompt Injection
AI agents that process external content (web pages, documents, emails) are vulnerable to **prompt injection** — hidden instructions that manipulate the agent's behavior.
**Risks**:
- A webpage or document could contain hidden instructions that cause the agent to perform unintended actions
- Data exfiltration through crafted prompts
- Actions performed on behalf of an attacker
**Mitigations**:
- Be cautious about what content you ask the agent to process
- Review agent actions in the logs
- Limit the entities and services exposed to the agent
---
## Best Practices Summary
| Practice | Priority |
|---|---|
| Use HTTPS for remote access | High |
| Keep `gateway_bind_mode: loopback` unless LAN access is needed | High |
| Only install skills from trusted sources | High |
| Review exposed entities in Assist pipeline | High |
| Keep the add-on updated | High |
| Use a dedicated HA user for the `homeassistant_token` | Medium |
| Monitor add-on logs regularly | Medium |
| Rotate gateway tokens periodically | Medium |
| Restrict router SSH user permissions | Medium |
| Back up your configuration regularly | Low |
---
## Reporting Security Issues
If you discover a security vulnerability in this add-on, please report it responsibly by opening a private security advisory on GitHub rather than a public issue.
---
*This document does not constitute legal advice. Consult a qualified professional for legal guidance specific to your situation.*