AgapHost/adolf/README.md

Adolf — OpenClaw gateway deployment

Adolf is the self-hosted OpenClaw fork that runs as the adolf container (Matrix-first personal assistant). This directory holds its version-controlled gateway configuration.

• Source tree (the OpenClaw fork being built): /home/alvis/adolf
• Compose service adolf lives in: openai/docker-compose.yml
• This config directory lives at the repo root (agap_git/adolf/), not nested inside openai/, since it is shared config rather than part of the openai compose project's own tree.
• Model backend: adolf-llm container (Kimi-CLI wrapper) on :8010

Config source of truth

The gateway config is openclaw.json in this directory. It is bind-mounted read-only over the adolf-state volume:

volumes:
  - adolf-state:/home/node/.openclaw                         # runtime state only
  - ../adolf/openclaw.json:/home/node/.openclaw/openclaw.json:ro  # tracked config

Previously this file was a hand-edited copy inside the adolf-state Docker volume (edited via docker cp into the running container). It is now tracked in git and seeded into the container by the mount, so git is the single source of truth.

• The file is JSONC (comments + unquoted keys allowed).
• No secrets live here. Every credential is a ${VAR} reference resolved from the container's environment, which is sourced from openai/.env (gitignored, never committed): OPENCLAW_GATEWAY_TOKEN, ADOLF_KEY, MATRIX_*, MARKETPLACE_MCP_TOKEN.
• The gateway reads this file and writes its own openclaw.json.last-good and openclaw.json.rejected.* snapshots into the volume dir (writable). It does not rewrite this file, so the read-only mount is safe.

Changing the config

1. Edit agap_git/adolf/openclaw.json.
2. Restart the container:

   env -u HTTPS_PROXY -u HTTP_PROXY -u ALL_PROXY -u https_proxy -u http_proxy -u all_proxy \
     docker compose -f /home/alvis/agap_git/openai/docker-compose.yml up -d adolf
   

3. Verify it came up healthy and the config was accepted:

   env -u HTTPS_PROXY -u HTTP_PROXY -u ALL_PROXY -u https_proxy -u http_proxy -u all_proxy \
     docker ps --filter name=adolf --format '{{.Names}} {{.Status}}'
   env -u HTTPS_PROXY -u HTTP_PROXY -u ALL_PROXY -u https_proxy -u http_proxy -u all_proxy \
     docker logs --tail 40 adolf
   

   A fresh openclaw.json.rejected.* file in /home/node/.openclaw means the edit failed validation and the previous .last-good is still in use.

Because the mount is read-only, editing config through the gateway UI/API is intentionally disabled — all changes go through git.

Granting a Matrix user access to Adolf

Adolf only responds to Matrix users on an allow-list. This is the channels.matrix.dm block in openclaw.json:

channels: {
  matrix: {
    enabled: true,
    encryption: true,
    dm: {
      policy: "allowlist",
      allowFrom: [
        "@admin:mtx.alogins.net",
        "@elizaveta:mtx.alogins.net",
      ],
    },
    groupPolicy: "disabled",   // no group-room handling yet
    autoJoin: "always",
  },
}

• dm.policy: "allowlist" — only users whose full Matrix ID appears in allowFrom can DM the bot. Everyone else is ignored. (policy: "pairing" is the alternative: the owner must approve each unknown sender interactively. allowlist is stricter and declarative.)
• dm.allowFrom — the list of authorized Matrix user IDs.
• groupPolicy: "disabled" — Adolf does not act in group rooms; DM only.

To grant a new user access

1. Get the user's full Matrix ID, e.g. @ivan:mtx.alogins.net.
2. Add it to allowFrom in agap_git/adolf/openclaw.json:

   allowFrom: [
     "@admin:mtx.alogins.net",
     "@elizaveta:mtx.alogins.net",
     "@ivan:mtx.alogins.net",
   ],
   

3. Restart adolf (see "Changing the config" above).
4. The user can now start a DM with Adolf's Matrix account (MATRIX_USER_ID in openai/.env). autoJoin: "always" means Adolf auto-accepts the DM invite; conversation is end-to-end encrypted (encryption: true).

To revoke access, remove the ID from allowFrom and restart.

Matrix accounts themselves are created on the Synapse homeserver (mtx.alogins.net) — see the AgapHost wiki Matrix page. The allow-list here only controls which existing Matrix users Adolf will talk to.