# OpenClaw Assistant (Home Assistant Add-on)

This add-on runs a OpenClaw Assistant instance on Home Assistant OS (Supervisor add-on).

> Note: The upstream project has gone through renames. This add-on installs **OpenClaw**.

## What this add-on provides

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

This avoids Home Assistant Ingress websocket edge-cases.

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

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

### Required
- `telegram_bot_token`

### Recommended baseline (safe defaults)
- `gateway_bind: loopback`
- `gateway_port: 18789`
- `gateway_token: ""` (auto-generated by gateway when loopback)
- `enable_terminal: false`

### Terminal (Ingress) setup
To enable the embedded web terminal:
- Set `enable_terminal: true`

Then open the add-on Ingress page. You will see a terminal iframe.

Security note: the terminal is powerful. Only enable if you trust HA admins with shell access
inside the add-on container.

### Gateway Web UI (separate tab) setup
To open the gateway UI in a separate tab reliably:

1) Expose the gateway:
- Set `gateway_bind: lan`
- Set `gateway_port` (default `18789`)
- Set a **fixed** `gateway_token` (required when `gateway_bind=lan`)

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**).

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)

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

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

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**.

## Troubleshooting

### Terminal doesn’t show
- 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.