Refresh README/DOCS for new onboarding flow; bump add-on to 0.5.8
This commit is contained in:
root
@@ -1,107 +1,104 @@
|
|||||||
# OpenClaw Assistant (Home Assistant Add-on)
|
# 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)
|
### Ingress page (inside Home Assistant)
|
||||||
The add-on’s **Ingress UI** is intentionally kept simple and reliable:
|
The add-on’s Ingress UI is intentionally simple and reliable:
|
||||||
- a landing page
|
- A landing page
|
||||||
- an **embedded web terminal** (optional)
|
- An embedded **web terminal** (ttyd)
|
||||||
- a button/link that opens the **Gateway Web UI in a separate browser tab** (not embedded)
|
- 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)
|
## OpenClaw configuration philosophy
|
||||||
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.
|
### 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
|
## 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
|
1) Home Assistant → Settings → Add-ons → Add-on store
|
||||||
All configuration is done via the add-on UI (Options).
|
2) Add repository URL:
|
||||||
|
- Add-on store → ⋮ → Repositories → paste:
|
||||||
|
- `https://github.com/techartdev/OpenClawHomeAssistant`
|
||||||
|
3) Install **OpenClaw Assistant**
|
||||||
|
|
||||||
### Required
|
## First-time setup checklist
|
||||||
- `telegram_bot_token`
|
|
||||||
|
|
||||||
### Recommended baseline (safe defaults)
|
1) Open the add-on page (Ingress)
|
||||||
- `gateway_bind: loopback`
|
2) Use the terminal and run:
|
||||||
- `gateway_port: 18789`
|
- `openclaw onboard`
|
||||||
- `gateway_token: ""` (auto-generated by gateway when loopback)
|
- or `openclaw configure`
|
||||||
- `enable_terminal: false`
|
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
|
Once `gateway_public_url` is set and OpenClaw has a gateway token, the landing page will show an “Open Gateway Web UI” button.
|
||||||
To enable the embedded web terminal:
|
|
||||||
- Set `enable_terminal: true`
|
|
||||||
|
|
||||||
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
|
### Terminal (Ingress)
|
||||||
inside the add-on container.
|
- `enable_terminal` (default `true`)
|
||||||
|
|
||||||
### Gateway Web UI (separate tab) setup
|
Security note: the terminal gives shell access inside the add-on container.
|
||||||
To open the gateway UI in a separate tab reliably:
|
Enable it only if you trust your HA admins.
|
||||||
|
|
||||||
1) Expose the gateway:
|
### Gateway UI link
|
||||||
- Set `gateway_bind: lan`
|
- `gateway_public_url` (optional)
|
||||||
- Set `gateway_port` (default `18789`)
|
|
||||||
- Set a **fixed** `gateway_token` (required when `gateway_bind=lan`)
|
|
||||||
|
|
||||||
2) Tell the add-on what URL to open:
|
This does not expose anything by itself; it just controls what URL the Ingress button opens.
|
||||||
- Set `gateway_public_url` to a base URL that the browser can reach (recommended: **no trailing slash**).
|
|
||||||
|
|
||||||
Examples:
|
### Home Assistant token
|
||||||
- LAN only: `http://homeassistant.local:18789` (or `http://192.168.1.10:18789`)
|
- `homeassistant_token` (optional)
|
||||||
- Public domain with port-forward: `https://example.duckdns.org:12345`
|
|
||||||
- (in that case your router/NAT must forward `12345` → HA host → gateway port)
|
|
||||||
|
|
||||||
The Ingress landing page button will open:
|
If set, it is written to:
|
||||||
|
- `/config/secrets/homeassistant.token`
|
||||||
`<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
|
|
||||||
|
|
||||||
### Router SSH (generic)
|
### Router SSH (generic)
|
||||||
This add-on supports a **generic SSH configuration** for a router/firewall (or any LAN network device)
|
These options are for custom automations that need SSH access to a router/firewall or other LAN device:
|
||||||
when you want the assistant to automate local network changes (e.g., port forwarding, DNS records,
|
- `router_ssh_host`
|
||||||
firewall rules).
|
- `router_ssh_user`
|
||||||
|
- `router_ssh_key_path` (default `/data/keys/router_ssh`)
|
||||||
|
|
||||||
Config fields:
|
How to provide the key:
|
||||||
- `router_ssh_host`: host/IP of the router (reachable from the HA host network)
|
- Put the private key file under the add-on config directory so it appears in-container at `/data/keys/...`
|
||||||
- `router_ssh_user`: SSH username
|
- Recommended permissions: `chmod 600`
|
||||||
- `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**.
|
|
||||||
|
|
||||||
## Troubleshooting
|
## 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`
|
- Ensure `enable_terminal=true`
|
||||||
- Check add-on logs for `Starting web terminal (ttyd)`
|
- Check 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.
|
|
||||||
|
|||||||
@@ -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
|
## 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
|
- An always-on OpenClaw gateway running as a Supervisor-managed add-on.
|
||||||
- Gateway binds to **loopback** by default (not exposed on LAN)
|
- A reliable **Ingress landing page** inside Home Assistant that includes:
|
||||||
- Terminal is **off by default**
|
- an embedded **web terminal** (ttyd)
|
||||||
- Tokens/IDs are provided via add-on options and are never hardcoded
|
- 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)
|
## Why the Gateway UI is not embedded in Ingress
|
||||||
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)
|
|
||||||
|
|
||||||
## Setup / Docs
|
The Gateway Web UI requires WebSockets that can be flaky through HA Ingress depending on proxying/mixed-content.
|
||||||
See **DOCS.md** for the supported setups:
|
So we **don’t embed** it. Instead, the Ingress page gives you a button that opens the Gateway UI directly using
|
||||||
- embedded terminal via Ingress
|
`gateway_public_url`.
|
||||||
- opening Gateway Web UI in a new tab (not embedded)
|
|
||||||
|
|
||||||
## Configuration
|
## Security model (high level)
|
||||||
All configuration is done via the add-on UI.
|
|
||||||
See the schema in `openclaw_assistant/config.yaml`.
|
|
||||||
|
|
||||||
### Optional: Brave Search
|
- The add-on **does not** manage or overwrite OpenClaw’s full config.
|
||||||
If you provide `brave_api_key`, the add-on exports `BRAVE_API_KEY` for the assistant’s web search tool.
|
- 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
|
## Install
|
||||||
If you provide `homeassistant_token`, it is written to `/config/secrets/homeassistant.token` inside the container for local scripts/tools.
|
|
||||||
|
|
||||||
### Optional: Router SSH (generic)
|
1. Home Assistant → **Settings → Add-ons → Add-on store**
|
||||||
If you want the assistant to automate local network/router configuration over SSH, see **DOCS.md** (Router SSH section).
|
2. **⋮ → Repositories**
|
||||||
|
3. Add this repo:
|
||||||
|
- `https://github.com/techartdev/OpenClawHomeAssistant`
|
||||||
|
4. Install **OpenClaw Assistant**
|
||||||
|
|
||||||
## UI
|
## First run (recommended)
|
||||||
- The main add-on page loads the Gateway UI via **Ingress**.
|
|
||||||
- If enabled, web terminal is available at `/terminal/` under the ingress UI.
|
|
||||||
|
|
||||||
## Status
|
1. Open the add-on page (Ingress) and use the embedded terminal.
|
||||||
This is still in "draft" while we finalize naming, docs, and a public release process.
|
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.
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
name: OpenClaw Assistant
|
name: OpenClaw Assistant
|
||||||
version: "0.5.7"
|
version: "0.5.8"
|
||||||
slug: openclaw_assistant
|
slug: openclaw_assistant
|
||||||
description: Run OpenClaw Assistant (OpenClaw-compatible) as a Home Assistant add-on.
|
description: Run OpenClaw Assistant (OpenClaw-compatible) as a Home Assistant add-on.
|
||||||
url: https://github.com/techartdev/OpenClawHomeAssistant
|
url: https://github.com/techartdev/OpenClawHomeAssistant
|
||||||
|
|||||||
Reference in New Issue
Block a user