From 1c01ccd311cc74d77e327e3dadc3bf661dde7e16 Mon Sep 17 00:00:00 2001 From: root Date: Sat, 31 Jan 2026 00:46:19 +0200 Subject: [PATCH] Refresh README/DOCS for new onboarding flow; bump add-on to 0.5.8 --- DOCS.md | 157 ++++++++++++++++----------------- README.md | 79 ++++++++++------- openclaw_assistant/config.yaml | 2 +- 3 files changed, 123 insertions(+), 115 deletions(-) diff --git a/DOCS.md b/DOCS.md index 53bcc05..40b4f6f 100644 --- a/DOCS.md +++ b/DOCS.md @@ -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: - -`/?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)` diff --git a/README.md b/README.md index 162832d..8a2f1ec 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/openclaw_assistant/config.yaml b/openclaw_assistant/config.yaml index 286988e..1add817 100644 --- a/openclaw_assistant/config.yaml +++ b/openclaw_assistant/config.yaml @@ -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