TetraHome/Tetra-AI-HA-App
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8007c6e907437bbae16aac417502e095b64bb0b4
Tetra-AI-HA-App/DOCS.md
T

7.7 KiB
Raw Blame History

OpenClaw Assistant (Home Assistant Add-on)

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

It’s designed to be friendly to non-technical users:

  • The add-on provides a simple Home Assistant page (Ingress) with a terminal.
  • You complete setup using OpenClaw’s built-in onboarding commands.

0) What is what? (quick explanation)

  • Ingress page (inside Home Assistant): a landing page + terminal.
  • Gateway: the OpenClaw server running inside the add-on container.
  • Gateway Web UI (Control UI): the web interface you open in your browser.

The Gateway UI is opened in a separate tab (not embedded), because Home Assistant Ingress can have WebSocket issues.

1) Install the add-on

  1. Home Assistant → Settings → Add-ons → Add-on store
  2. Add repository URL:
  • Add-on store → ⋮ → Repositories → paste:
    • https://github.com/techartdev/OpenClawHomeAssistant
  1. Install OpenClaw Assistant
  2. Start the add-on

2) First-time setup (step-by-step)

Open the add-on page (Ingress). You will see:

  • Open Gateway Web UI button
  • Terminal embedded on the page

Step A — Run OpenClaw onboarding

In the terminal, run:

  • Recommended:
    • openclaw onboard

If you prefer:

  • openclaw configure

Follow the prompts.

Step B — Get your Gateway token (needed for the Web UI)

In the terminal run:

openclaw config get gateway.auth.token

Copy the token somewhere safe.

Step C — Make the Gateway reachable from your browser

You have two common setups:

Option 1: Use Home Assistant HTTPS (recommended)

If your Home Assistant is already exposed via HTTPS (Nabu Casa, reverse proxy, etc.), use that. This avoids browser security issues.

Option 2: LAN access (http://192.168.x.x) — using add-on options (recommended)

The easiest way to enable LAN access is via the add-on configuration:

  1. Go to Home Assistant → Settings → Add-ons → OpenClaw Assistant → Configuration
  2. Set the following options:
    • gateway_bind_mode: lan (enables LAN binding; use loopback for local-only access)
    • gateway_port: 18789 (or your preferred port)
    • allow_insecure_auth: true (required for HTTP access; see section 4 below)
  3. Restart the add-on

The add-on will automatically update OpenClaw's configuration on startup.

Option 3: LAN access — manual configuration (advanced)

If you prefer to configure manually via terminal:

openclaw config set gateway.bind lan
openclaw config set gateway.port 18789
openclaw config set gateway.mode local

Then restart the add-on.

3) Configure the “Open Gateway Web UI” button

The button uses the add-on option:

  • gateway_public_url

Set it in Home Assistant → Add-on configuration.

Examples:

  • LAN:
    • http://192.168.1.119:18789
  • Public HTTPS:
    • https://example.duckdns.org:12345

The button will open:

<gateway_public_url>/?token=<your_token>

If the UI says Unauthorized, you likely used the wrong token. Re-check it with:

openclaw config get gateway.auth.token

4) Important: “requires HTTPS or localhost (secure context)”

Modern browsers sometimes refuse to run the Control UI on plain HTTP unless it is localhost. If you open the Gateway UI over LAN HTTP and see:

control ui requires HTTPS or localhost (secure context)

You have 3 options:

Option A — Use HTTPS (best)

Put the gateway behind HTTPS (recommended long-term).

Option B — Use localhost via port-forward

Access it as http://localhost:18789 using SSH port forwarding from your computer.

Option C — Allow insecure auth (quick workaround; less secure)

Via add-on configuration (recommended):

  1. Go to Home Assistant → Settings → Add-ons → OpenClaw Assistant → Configuration
  2. Set allow_insecure_auth: true
  3. Restart the add-on

Via terminal (manual):

openclaw config set gateway.controlUi.allowInsecureAuth true

Then restart the add-on.

This allows using the Control UI over LAN HTTP.

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

This add-on keeps options minimal but practical. See openclaw_assistant_dev/config.yaml for the full schema.

Gateway Network Settings

Control how the OpenClaw gateway operates and binds to the network:

  • gateway_mode (string: local or remote, default local)

    • local: Run the gateway locally in this add-on (recommended for most users)
    • remote: Connect to a remote gateway running elsewhere
    • This setting determines whether OpenClaw runs its own gateway or connects to an existing one

  • gateway_bind_mode (string: loopback or lan, default loopback)

    • loopback: Bind to 127.0.0.1 only — secure, local access only
    • lan: Bind to all interfaces — accessible from your local network
    • Only applies when gateway_mode is local

  • gateway_port (int, default 18789)

    • Port number for the gateway to listen on
    • Only applies when gateway_mode is local

  • allow_insecure_auth (bool, default false)

    • Allow HTTP authentication for gateway access on LAN
    • WARNING: Only enable if using HTTP (not HTTPS) for gateway_public_url
    • Required for browser access over HTTP (see section 4)

These settings are applied automatically on add-on startup. No need to run openclaw config commands manually.

Terminal

  • enable_terminal (bool, default true)

    • Enable or disable the web terminal button inside Home Assistant

  • terminal_port (int, default 7681)

    • Port number for the web terminal (ttyd) to listen on
    • Change this if port 7681 conflicts with another service on your system
    • Valid range: 1024-65535

Security note: the terminal gives shell access inside the add-on container.

Home Assistant token

  • homeassistant_token (optional)

If set, it is written to:

  • /config/secrets/homeassistant.token

Router SSH (generic)

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

Session cleanup

  • clean_session_locks_on_start (bool, default true) — Remove stale lock files on startup
  • clean_session_locks_on_exit (bool, default true) — Remove stale lock files on shutdown

Troubleshooting

Some skills fail to install (Homebrew errors)

If you see errors like:

  • Homebrew's x86_64 support on Linux requires a CPU with SSSE3 support!
  • spawn brew ENOENT or brew: command not found

Cause: Your CPU doesn't support SSSE3 instructions (required by Homebrew). This affects older CPUs like some Intel Atom, Celeron, or pre-2006 processors.

Impact: Skills that depend on CLI tools installed via Homebrew (e.g., gemini, aider) won't install. Core OpenClaw functionality still works.

Solutions:

  1. Use a newer CPU with SSSE3 support (Intel Core 2 or newer, ~2006+)
  2. Install dependencies manually if you know which tools are needed
  3. Use alternative skills that don't require Homebrew dependencies

The add-on will still start and work - Homebrew is optional.

I get ERR_CONNECTION_REFUSED

  • The gateway is not reachable at that IP/port.
  • Confirm bind/port in terminal:
    • openclaw config get gateway.bind
    • openclaw config get gateway.port

The Gateway UI opens but shows Unauthorized

  • Fetch the token:
    • openclaw config get gateway.auth.token

Terminal isn’t visible

  • Ensure enable_terminal=true
  • Check logs for Starting web terminal (ttyd)
Reference in New Issue View Git Blame Copy Permalink