# OpenClaw Assistant (Home Assistant Add-on)

This add-on runs **OpenClaw** inside **Home Assistant OS (HAOS)**.

The project deliberately keeps the add-on thin:
- Home Assistant provides the container lifecycle + Ingress
- OpenClaw provides onboarding/configuration and all assistant features

## UI / Ingress behavior

### 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

### 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`).

## 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:
  - `https://github.com/techartdev/OpenClawHomeAssistant`
3) Install **OpenClaw Assistant**

## First-time setup checklist

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`

Once `gateway_public_url` is set and OpenClaw has a gateway token, the landing page will show an “Open Gateway Web UI” button.

## Add-on options (custom / HA-specific)

### Terminal (Ingress)
- `enable_terminal` (default `true`)

Security note: the terminal gives shell access inside the add-on container.
Enable it only if you trust your HA admins.

### Gateway UI link
- `gateway_public_url` (optional)

This does not expose anything by itself; it just controls what URL the Ingress button opens.

### Home Assistant token
- `homeassistant_token` (optional)

If set, it is written to:
- `/config/secrets/homeassistant.token`

### Router SSH (generic)
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`)

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

### 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 logs for `Starting web terminal (ttyd)`