---
name: lisa-openclaw-connect-repo-topic
description: "Bind a Telegram forum topic to…"
---

# lisa-openclaw-connect-repo-topic

Turn a Telegram forum topic into a repeatable OpenClaw entrypoint for code work. A **dispatcher**
agent receives the request and delegates; a **worker** agent runs the local coding CLI in a safe
target directory and relays the result.

This SKILL.md is complete and runnable under both Claude Code and Codex (no command/`$ARGUMENTS`
layer in Codex). Keep real ids/handles/paths out of committed files — they go only in
`~/.openclaw/openclaw.json`. For exact config shapes read
[references/repo-topic-config.md](references/repo-topic-config.md).

## Prerequisites

- `lisa-openclaw-setup` has run and its capability probes passed.
- A Telegram supergroup with forum topics, and a bot that is (or can be promoted to) a **group
  admin** — bot presence alone is not enough for topic routing.

## Boundaries (apply every time)

- groups = the human trust boundary
- topics = the project-routing boundary
- native-reply roots = the short-term session boundary inside a topic
- agents = the capability boundary
- Do not mix admin-only repos with broader-collaboration repos in one group. If two repos need
  different member lists, use separate groups, not topic-only separation.

## Scope modes (pick exactly one per topic)

- **`single-repo`** — the topic is pinned to one repo directory; the dispatcher never asks which repo.
- **`folder-scoped`** — the topic is pinned to a parent folder containing multiple repos; the
  dispatcher must confirm the inferred repo(s) unless the user named them explicitly.

Do not mix both behaviors in one topic.

## Required inputs

- trust boundary: `admin` or `developer`
- scope mode: `single-repo` or `folder-scoped`
- access surface: Telegram group + topic (by name; ids captured during the run)
- the bot handle to bind
- workspace root on disk (repo dir for single-repo; parent folder for folder-scoped)
- allowed Telegram user ids
- completion policy:
  - `admin` topics may request change + docs + commit + PR + merge
  - `developer` topics default to change + docs + commit + PR only
- for `folder-scoped`: a repo catalog (label, absolute path, a few matching keyword hints)

## Workflow

### 1. Resolve the contract

Confirm the trust boundary, scope mode, workspace root, bot handle, and (for folder-scoped) the repo
catalog. If a needed agent doesn't exist yet, create it in step 3.

### 2. Provision / reuse the Telegram surface

Reuse the trust-matched group and the exact topic if they already exist; otherwise create them (enable
forum/topics mode first). Ensure the bot is in the group and **promoted to admin**. Telegram Bot API
cannot list groups by name — discover ids from a logged-in Telegram client, an existing route in
`~/.openclaw/openclaw.json`, or a received Bot API update. If browser/UI automation blocks on a human
confirmation step, give the user only the blocked step, wait, then resume.

### 3. Implement the dispatcher + worker pair

Create or update two agents (exact tool-deny shapes in
[references/repo-topic-config.md](references/repo-topic-config.md)):

- **`<topic-slug>-dispatch`** — skill-aware entrypoint; tools restricted to delegation/session tools
  (+ optional `read`); denies file writes, shell/exec, browser, gateway, automation; may delegate
  only to `<topic-slug>-codex`.
- **`<topic-slug>-codex`** — restricted worker; keeps `read` + `exec`; denies session spawning,
  browser, gateway, and direct file-write tools; runs the local coding CLI for the actual work.

### 4. Repo-selection behavior

- `single-repo`: treat the repo as decided; pass the fixed repo path to the worker; never ask.
- `folder-scoped`: infer candidates from the catalog. If the user named repo(s) explicitly, skip
  confirmation; otherwise ask before spawning:
  - one likely repo: `This looks like <repo>. Is that correct?`
  - multiple: `This may belong to <repo-1> or <repo-2>. Is that correct, or which repo(s)?`
  On confirmation of multiple repos, spawn one worker run per repo (or ask the user to split a
  too-coupled change). Never skip confirmation in folder-scoped mode unless selection was explicit.

### 5. Worker safety contract

Every worker task receives an explicit repo path and:

1. inspects `git status --short --branch` in the selected repo
2. if the primary checkout is dirty or already on a feature branch, creates a temporary worktree from
   `main` under `/tmp`
3. trusts local tool config in a fresh worktree if required (e.g. `mise trust <target_dir>`)
4. runs the coding CLI in the foreground in the target directory
5. cleans up the temporary worktree after success when safe

The worker prepares the safe target and launches the CLI; it does not edit files directly.

### 6. Bind the topic

Route the topic to the dispatcher. In single-account Telegram configs, set
`channels.telegram.groups.<group-id>.topics.<topic-id>.agentId = <topic-slug>-dispatch`. In
multi-account Telegram configs, set the same route under the owning bot account:
`channels.telegram.accounts.<account-id>.groups.<group-id>.topics.<topic-id>.agentId =
<topic-slug>-dispatch`. Account configs do not inherit root `channels.telegram.groups` routes, so a
root-only route can validate while the actual bot still ignores the topic-level `requireMention`,
`agentId`, and prompt. When in doubt, mirror the route under the owning account and keep any existing
root group route only as a fallback/documentation shape.

Account-scoped topic `agentId` routes also require an OpenClaw runtime that treats the topic agent as
an explicit group route for non-default Telegram accounts. If the self-test logs
`drop non-default account requires explicit binding`, update or rebuild OpenClaw before adding config
workarounds; do not create persistent ACP bindings solely to bypass that guard.

Keep allowlist policy, and add `allowFrom` only when membership must be narrower than the group.
Leave the topic-level `requireMention = false` (the default) so the agent activates on any message —
the topic is bound 1:1 to this dispatcher, so an @mention carries no routing information and is pure
friction. Set it to `true` only for a shared-workspace topic where humans also coordinate with each
other and you don't want every line to spawn a run; the group-level `requireMention` stays `true`
regardless. See "Mention gating" in [references/repo-topic-config.md](references/repo-topic-config.md)
for the tradeoff. The topic `systemPrompt` must state the scope mode, treat each native-reply root as
an independent request context, confirm repo selection only in folder-scoped mode, spawn the worker
with an explicit repo path, and return the worker result to the topic. If the route may return
generated files, the prompt must also say to write or copy returnable artifacts under
`~/.openclaw/media` before calling `message(action="send")`, because outbound local media delivery
rejects arbitrary `/tmp` paths. Back up `~/.openclaw/openclaw.json` before editing and preserve
unrelated routes.

### 7. Validate + self-test

```sh
openclaw config validate
openclaw gateway restart
openclaw gateway status
openclaw channels status --probe
```

Then from the target topic, send a plain message with **no** @mention (the default
`requireMention = false` means the agent must activate without one) asking for an exact-token reply
with **no** file changes, commits, PRs, or merges, e.g. `reply with exactly TELEGRAM-ROUTE-OK`.
Confirm the visible reply, that the dispatcher spawned the worker, and that the worker ran in the
intended repo. If there is no dispatcher session, inspect `/tmp/openclaw/openclaw-YYYY-MM-DD.log`;
`drop non-default account requires explicit binding` means the OpenClaw runtime is too old for
account-scoped topic-agent routing. If the topic was deliberately left at `requireMention = true`,
mention the bot instead (`<bot-handle> reply with exactly TELEGRAM-ROUTE-OK`) and additionally
confirm that an un-mentioned message is **ignored**. For folder-scoped topics, also send a request
that implies but doesn't name a repo and confirm the dispatcher asks for confirmation before
proceeding. Do **not** treat `openclaw agent --agent <id> ...` as proof a topic route works — use the
visible topic reply.

## Output standard

Finish with: group id + topic id used; scope mode; workspace root and repo path or catalog;
dispatcher + worker agent ids; whether the bot is confirmed group admin; validation results; whether
the self-test passed; and any remaining manual follow-up or trust caveat.

## Related

`lisa-openclaw-setup` (run first), `lisa-openclaw-connect-staff` (facilitator/specialist staff on
Telegram or Slack).
