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

Refresh README/DOCS for new onboarding flow; bump add-on to 0.5.8

Browse Source
This commit is contained in:
root
2026-01-31 00:46:19 +02:00
parent 62ef146c3b
commit 1c01ccd311
3 changed files with 123 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOCS.md
+77 -80
View File
@@ -1,107 +1,104 @@
# OpenClaw Assistant (Home Assistant Add-on)
This add-on runs a OpenClaw Assistant instance on Home Assistant OS (Supervisor add-on).
This add-on runs **OpenClaw** inside **Home Assistant OS (HAOS)**.
> Note: The upstream project has gone through renames. This add-on installs **OpenClaw**.
The project deliberately keeps the add-on thin:
- Home Assistant provides the container lifecycle + Ingress
- OpenClaw provides onboarding/configuration and all assistant features
## What this add-on provides
## UI / Ingress behavior
### 1) Ingress page (embedded)
The add-on’s **Ingress UI** is intentionally kept simple and reliable:
- a landing page
- an **embedded web terminal** (optional)
- a button/link that opens the **Gateway Web UI in a separate browser tab** (not embedded)
### Ingress page (inside Home Assistant)
The add-on’s Ingress UI is intentionally simple and reliable:
- A landing page
- An embedded **web terminal** (ttyd)
- A button that opens the **Gateway Web UI** in a separate tab
This avoids Home Assistant Ingress websocket edge-cases.
### Gateway Web UI (separate tab)
The Gateway Web UI requires WebSockets. Rather than tunneling it through HA Ingress,
we open it directly using a user-provided base URL (`gateway_public_url`).
### 2) Gateway Web UI (separate tab)
The Gateway Web UI requires websockets. Instead of trying to tunnel that through HA Ingress,
we open it directly using a user-provided public/base URL.
## OpenClaw configuration philosophy
### We do NOT overwrite OpenClaw config
OpenClaw’s config/state lives under:
- `/config/.openclaw/` (inside the container)
The add-on **does not** rewrite OpenClaw’s configuration on each start.
You should use OpenClaw’s own interactive tooling:
- `openclaw setup`
- `openclaw onboard`
- `openclaw configure`
### Minimal bootstrap (first boot only)
If `/config/.openclaw/openclaw.json` is missing, the add-on bootstraps a minimal strict-JSON config so that
`openclaw gateway run` can start:
- `gateway.mode = local`
- `gateway.auth.mode = token`
- `gateway.auth.token` generated
After that, onboarding/configure can expand the config normally.
## Installation
1. Home Assistant → Settings → Add-ons → Add-on store
2. Add repository URL:
- Add-on store → ⋮ → Repositories → paste the GitHub repo URL
3. Install **OpenClaw Assistant**
## Configuration overview
All configuration is done via the add-on UI (Options).
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**
### Required
- `telegram_bot_token`
## First-time setup checklist
### Recommended baseline (safe defaults)
- `gateway_bind: loopback`
- `gateway_port: 18789`
- `gateway_token: ""` (auto-generated by gateway when loopback)
- `enable_terminal: false`
1) Open the add-on page (Ingress)
2) Use the terminal and run:
- `openclaw onboard`
- or `openclaw configure`
3) Optional (recommended): set `gateway_public_url` in add-on options.
- Example (LAN): `http://192.168.1.10:18789`
- Example (public): `https://example.duckdns.org:12345`
### Terminal (Ingress) setup
To enable the embedded web terminal:
- Set `enable_terminal: true`
Once `gateway_public_url` is set and OpenClaw has a gateway token, the landing page will show an “Open Gateway Web UI” button.
Then open the add-on Ingress page. You will see a terminal iframe.
## Add-on options (custom / HA-specific)
Security note: the terminal is powerful. Only enable if you trust HA admins with shell access
inside the add-on container.
### Terminal (Ingress)
- `enable_terminal` (default `true`)
### Gateway Web UI (separate tab) setup
To open the gateway UI in a separate tab reliably:
Security note: the terminal gives shell access inside the add-on container.
Enable it only if you trust your HA admins.
1) Expose the gateway:
- Set `gateway_bind: lan`
- Set `gateway_port` (default `18789`)
- Set a **fixed** `gateway_token` (required when `gateway_bind=lan`)
### Gateway UI link
- `gateway_public_url` (optional)
2) Tell the add-on what URL to open:
- Set `gateway_public_url` to a base URL that the browser can reach (recommended: **no trailing slash**).
This does not expose anything by itself; it just controls what URL the Ingress button opens.
Examples:
- LAN only: `http://homeassistant.local:18789` (or `http://192.168.1.10:18789`)
- Public domain with port-forward: `https://example.duckdns.org:12345`
- (in that case your router/NAT must forward `12345` → HA host → gateway port)
### Home Assistant token
- `homeassistant_token` (optional)
The Ingress landing page button will open:
`<gateway_public_url>/?token=<gateway_token>`
Notes:
- This is intentionally **not embedded**.
- This avoids the unreliable “ingress websocket proxy” path.
## Optional options
- `telegram_allow_from`: comma-separated Telegram user IDs (locks DMs)
- `brave_api_key`: exported as `BRAVE_API_KEY` (for web search)
- `homeassistant_token`: written to `/config/secrets/homeassistant.token` inside the container
If set, it is written to:
- `/config/secrets/homeassistant.token`
### Router SSH (generic)
This add-on supports a **generic SSH configuration** for a router/firewall (or any LAN network device)
when you want the assistant to automate local network changes (e.g., port forwarding, DNS records,
firewall rules).
These options are 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`)
Config fields:
- `router_ssh_host`: host/IP of the router (reachable from the HA host network)
- `router_ssh_user`: SSH username
- `router_ssh_key_path`: path to the private key file inside the add-on (default: `/data/keys/router_ssh`)
How to provide the SSH key:
- Put the private key file under the add-on config directory so it appears in-container at `/data/keys/...`.
- Ensure permissions are restricted (recommended `chmod 600`).
Back-compat:
- Older versions used MikroTik-branded names: `mikrotik_host`, `mikrotik_ssh_user`, `mikrotik_ssh_key_path`.
These are still accepted but **deprecated**.
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`
## Troubleshooting
### Terminal doesn’t show
### Ingress loads but Gateway button is missing
- Set `gateway_public_url` in add-on options.
- If `gateway_public_url` is set but the button is still hidden, OpenClaw likely has not produced a gateway token yet.
Use the terminal and run `openclaw onboard` / `openclaw configure`.
### Gateway UI opens but doesn’t connect
- Confirm the browser can reach `gateway_public_url` (LAN routing / DNS / NAT).
- WebSockets must be allowed end-to-end.
### Terminal isn’t visible
- Ensure `enable_terminal=true`
- Check add-on logs for `Starting web terminal (ttyd)`
### Gateway button opens but UI says unauthorized
- Ensure `gateway_token` is set when using `gateway_bind=lan`.
- Ensure the opened URL includes `?token=...` (the add-on button does this automatically).
### Gateway button opens but cannot connect
- Confirm the browser can reach `gateway_public_url`.
- Confirm your NAT/port-forward rules.
- Check logs for `Starting web terminal (ttyd)`
README.md
+45 -34
View File
@@ -1,47 +1,58 @@
# OpenClaw Assistant – Home Assistant Add-on (Draft)
# OpenClaw Assistant – Home Assistant Add-on
This repository contains a Home Assistant add-on that runs an **OpenClaw Assistant** instance on **HAOS**.
This repository contains a Home Assistant add-on that runs **OpenClaw** inside **Home Assistant OS (HAOS)**.
Upstream note: the project has gone through renames. This add-on installs **OpenClaw**.
> Upstream rename history (FYI): clawdbot → moltbot → **openclaw** (final).
## What you get
- Always-on personal assistant running as a Supervisor-managed container
- Home Assistant **Ingress UI** (the assistant Gateway UI inside the add-on page)
- Optional **web terminal** inside Home Assistant (disabled by default)
- Persistent data stored under the add-on config directory (in-container: `/config`)
## Security defaults
- Gateway binds to **loopback** by default (not exposed on LAN)
- Terminal is **off by default**
- Tokens/IDs are provided via add-on options and are never hardcoded
- 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`).
## Install (high level)
1. Add this repo in Home Assistant:
Settings → Add-ons → Add-on Store → ⋮ → Repositories
2. Install **OpenClaw Assistant**
3. Configure options (at minimum: Telegram bot token)
## Why the Gateway UI is not embedded in Ingress
## Setup / Docs
See **DOCS.md** for the supported setups:
- embedded terminal via Ingress
- opening Gateway Web UI in a new tab (not embedded)
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`.
## Configuration
All configuration is done via the add-on UI.
See the schema in `openclaw_assistant/config.yaml`.
## Security model (high level)
### Optional: Brave Search
If you provide `brave_api_key`, the add-on exports `BRAVE_API_KEY` for the assistant’s web search tool.
- 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
### Optional: Home Assistant token
If you provide `homeassistant_token`, it is written to `/config/secrets/homeassistant.token` inside the container for local scripts/tools.
## Install
### Optional: Router SSH (generic)
If you want the assistant to automate local network/router configuration over SSH, see **DOCS.md** (Router SSH section).
1. Home Assistant → **Settings → Add-ons → Add-on store**
2. **⋮ → Repositories**
3. Add this repo:
- `https://github.com/techartdev/OpenClawHomeAssistant`
4. Install **OpenClaw Assistant**
## UI
- The main add-on page loads the Gateway UI via **Ingress**.
- If enabled, web terminal is available at `/terminal/` under the ingress UI.
## First run (recommended)
## Status
This is still in "draft" while we finalize naming, docs, and a public release process.
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.
## 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).
## Docs
See **DOCS.md** for more detailed setup and troubleshooting.
openclaw_assistant/config.yaml
+1 -1
View File
@@ -1,5 +1,5 @@
name: OpenClaw Assistant
version: "0.5.7"
version: "0.5.8"
slug: openclaw_assistant
description: Run OpenClaw Assistant (OpenClaw-compatible) as a Home Assistant add-on.
url: https://github.com/techartdev/OpenClawHomeAssistant