Skip to content

AGENTS.md

Latest commit

 

History

History
108 lines (81 loc) · 4.1 KB

AGENTS.md

File metadata and controls

108 lines (81 loc) · 4.1 KB

Repository Guidelines

Project Scope

This repository builds the OpenClaw Assistant (DEV) Home Assistant add-on. The add-on packages OpenClaw + nginx + ttyd and manages startup/configuration glue.

Architecture at a Glance

  • Add-on root metadata/docs:
    • README.md
    • DOCS.md
    • SECURITY.md
    • repository.yaml
  • Runtime implementation (all add-on behavior lives here):
    • openclaw_assistant_dev/run.sh (PID 1 orchestrator)
    • openclaw_assistant_dev/oc_config_helper.py (safe JSON config edits)
    • openclaw_assistant_dev/render_nginx.py (template rendering)
    • openclaw_assistant_dev/nginx.conf.tpl
    • openclaw_assistant_dev/landing.html.tpl
    • openclaw_assistant_dev/config.yaml (HA options + schema)
    • openclaw_assistant_dev/translations/*.yaml (all locale UI strings)
    • openclaw_assistant_dev/Dockerfile
    • openclaw_assistant_dev/CHANGELOG.md

Core Rules

  • Fix root causes, not symptoms.
  • Keep edits surgical; do not refactor unrelated code.
  • Never introduce insecure defaults.
  • Never log secrets or auth tokens.
  • Keep behavior backward-compatible unless the change explicitly requires a migration.

Add-on Config Coupling Rules (Critical)

When adding/changing any add-on option, update all of the following in one change:

  1. openclaw_assistant_dev/config.yaml
    • options: default
    • schema: validation entry
    • comments/help text
  2. openclaw_assistant_dev/translations/en.yaml
  3. openclaw_assistant_dev/translations/bg.yaml
  4. openclaw_assistant_dev/translations/de.yaml
  5. openclaw_assistant_dev/translations/es.yaml
  6. openclaw_assistant_dev/translations/pl.yaml
  7. openclaw_assistant_dev/translations/pt-BR.yaml
  8. DOCS.md configuration reference / troubleshooting if user-facing
  9. openclaw_assistant_dev/CHANGELOG.md

If any of these are skipped, the UX becomes inconsistent in HA.

Runtime Safety Rules

  • run.sh runs with set -euo pipefail; avoid constructs that fail unexpectedly under set -e.
  • Validate all user-provided values from /data/options.json before injecting into shell/nginx/openclaw config.
  • Keep run.sh idempotent on restart (multiple starts must not corrupt state).
  • Treat /config/ as persistent state; never wipe user data unless explicitly requested.

Gateway/Auth/Security Rules

  • OpenClaw v2026.2.22+ redacts sensitive values in openclaw config get.
    • For token retrieval guidance, prefer: jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json.
  • trusted-proxy mode may reject direct local CLI WS calls (trusted_proxy_user_missing); document this clearly instead of hiding it.
  • For lan_https certificate logic, keep SAN generation deterministic and regeneration-triggered on SAN/IP changes.

Template Coupling Rules

  • If adding placeholders in landing.html.tpl or nginx.conf.tpl, update render_nginx.py in the same change.
  • If landing-page guidance changes (commands/errors), sync corresponding troubleshooting text in DOCS.md.

Versioning and Changelog

  • User-visible changes should update:
    • openclaw_assistant_dev/CHANGELOG.md
    • openclaw_assistant_dev/config.yaml version
  • Keep changelog entries user-facing and action-oriented.

Coding Style

  • Shell: POSIX-friendly Bash, explicit quoting, descriptive variable names.
  • Python: small focused helpers, explicit error handling, no hidden side effects.
  • YAML/Markdown: preserve existing style and structure.
  • Avoid adding dependencies unless necessary.

Validation Checklist (Run After Relevant Changes)

From repo root:

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

For option changes:

  • verify config.yaml option + schema + all translations exist
  • verify DOCS.md matches current behavior

For startup/auth/proxy/cert changes:

  • verify log messages remain clear and actionable
  • verify landing.html.tpl instructions match actual commands

Commit Scope

  • Group related changes only.
  • Do not include unrelated formatting churn.
  • Do not edit generated/cache folders (__pycache__, temporary outputs).