TG Channel Manager

Pipeline: scout → draft → human approves → publisher.

Execution

python3 and curl are available in your environment (declared in requires.bins). Run all commands yourself using exec/bash tool. NEVER ask the user to run commands for you.

Startup

When you load this skill, run the preflight check FIRST:

python3 {baseDir}/scripts/tgcm.py --workspace {workspace} check

After check — act on results, don't ask:

• All [ok] → proceed with the user's task silently
• [fail] Bot token → ask the user for the token, then save it: tgcm.py config set bot-token . Do NOT ask where the token is or offer choices
• [warn] SEARXNG_URL → ask the user for the URL, then save it: tgcm.py config set searxng-url . Proceed without it — scout won't work but other commands will
• [fail] Channel → report which channel failed and why, include the fix from the output
• [warn] No channels → mention it, but proceed — the user may want to init one

Settings saved via config set persist in tgcm/.config.json and are used by all subsequent commands.

NEVER ask follow-up questions about check results. Report what's wrong and the fix from the output.

If the user hasn't specified a task — just report the check status, nothing else.

CLI Reference (FULL list — NO other commands exist)

All commands: python3 {baseDir}/scripts/tgcm.py --workspace {workspace}

Bot token is auto-resolved: --bot-token arg → $BOT_TOKEN env → openclaw.json (auto-search) → tgcm/.config.json. Just call tgcm.py get-id @username without --bot-token — the script finds the token itself. If auto-detection fails, save it once: tgcm.py config set bot-token .

Channel name validation: ^[a-z0-9][a-z0-9_-]{0,62}$.

Quick Reference

Recipes

Look up channel ID

python3 {baseDir}/scripts/tgcm.py get-id @username

Token is found automatically. Returns channel id, type, and title.

Connect a channel

1. Get ID: python3 {baseDir}/scripts/tgcm.py get-id @username
2. python3 {baseDir}/scripts/tgcm.py --workspace {workspace} init
3. python3 {baseDir}/scripts/tgcm.py --workspace {workspace} bind --channel-id
4. Configure skills.entries["tg-channel-manager"].config in openclaw.json
5. Add crons (see {baseDir}/references/cron-setup.md)

Load channel posts (rebuild dedup index)

python3 {baseDir}/scripts/tgcm.py --workspace {workspace} fetch-posts

Fetches posts from the channel's public page (t.me/s/) and adds them to content-index.json.

Options: --limit N (max pages, default 5), --dry-run (preview only).

Requires: channel must be public (have a @username).

View channels / status

• tgcm.py list
• tgcm.py info
• Queue: cat tgcm//content-queue.md

Do NOT

• Invent commands — the table above is the FULL list
• Publish posts directly — only cron Publisher does this
• Change draft → pending — only the human does this
• Skip dedup-check before drafting
• Ask the user to run commands — python3 and curl are available, use exec/bash yourself
• Ask the user for bot token or env vars — token is auto-resolved, check shows what's wrong
• Ask the user follow-up questions after check — report errors and the fix commands, don't offer choices
• Ask whether it's a channel or group — get-id returns the type field, this skill is for channels only

Data Layout

tgcm/
  channels.json            <- [{"name", "channelId", "status", "createdAt"}, ...]
  {channel-name}/
    channel.json           <- per-channel metadata
    content-index.json     <- dedup index
    content-queue.md       <- post queue

A channel is bound when channelId is set and status is "connected".

Configuration

Parameters are read from openclaw.json → skills.entries["tg-channel-manager"]:

Telegram

Limits & Schedule

Content

Post Style

Environment

Path Resolution

In sandbox mode (workspaceAccess: "none"), the workspace is under ~/.openclaw/sandboxes, not ~/.openclaw/workspace. Always use CWD-relative paths.

Cron setup: see {baseDir}/references/cron-setup.md.

Queue Format

Entry Format in content-queue.md

### <number>
- **Status:** draft | pending
- **Rubric:** <emoji> <name> (from config.rubrics)
- **Topic:** <topic>
- **Source:** <url> (for news)
- **Text:**

<post text>

Statuses:

• draft — awaiting approval
• pending — approved, ready for publishing

After publishing, the entry is removed from content-queue.md.

Deduplication

Before every draft — mandatory check:

python3 {baseDir}/scripts/dedup-check.py --base-dir <workspace> --topic "topic" --links "url1" "url2"

After publishing — add to index:

python3 {baseDir}/scripts/dedup-check.py --base-dir <workspace> --add <msgId> --topic "topic" --links "url"

Rebuild index (via Telegram search):

python3 {baseDir}/scripts/dedup-check.py --base-dir <workspace> --rebuild --channel-id <config.channelId>

Index is stored in /content-index.json (or per-channel: tgcm//content-index.json).