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

```yaml
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:
   ```bash
   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:
   ```bash
   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`:

```jsonc
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`:
   ```jsonc
   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.