OpenClaw Home Assistant Add-on Patterns

Always reuse existing logic in run.sh, oc_config_helper.py, and render_nginx.py. Avoid duplicate implementations for config parsing, gateway patching, or template rendering. Respect guidelines in AGENTS.md

Stack

Home Assistant add-on (Debian Bookworm base)
Bash runtime orchestrator (run.sh)
Python helper scripts for config/template work
nginx template rendering
YAML config schema + 6 locale translation files

Source of Truth

Add-on options/schema: openclaw_assistant_dev/config.yaml
Runtime boot logic: openclaw_assistant_dev/run.sh
Safe OpenClaw config edits: openclaw_assistant_dev/oc_config_helper.py
nginx + landing rendering: openclaw_assistant_dev/render_nginx.py
UI text in Home Assistant: openclaw_assistant_dev/translations/*.yaml
User-facing docs: DOCS.md

Required Sync Rules

When changing add-on options, update in the same PR:

config.yaml option default + schema
All translation files (en, bg, de, es, pl, pt-BR)
DOCS.md config/troubleshooting sections
CHANGELOG.md

When changing landing/nginx placeholders:

Keep template keys and render_nginx.py replacements in sync.

Security Rules

Do not log secrets/tokens.
For gateway token docs/UI guidance, do not use openclaw config get gateway.auth.token (redacted in v2026.2.22+).
Prefer jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json.

Editing Rules

Keep fixes minimal and root-cause focused.
Preserve backward compatibility for existing add-on options unless migration is explicit.
Do not change unrelated behavior while fixing one issue.

Validation Commands

bash -n openclaw_assistant_dev/run.sh
python3 -m py_compile openclaw_assistant_dev/oc_config_helper.py
python3 -m py_compile openclaw_assistant_dev/render_nginx.py

If behavior changes are user-visible, update openclaw_assistant_dev/CHANGELOG.md.

1.9 KiB Raw Blame History