Metadata

name: telegram-cli
description: Manage Telegram via tgctl CLI - send/forward/edit/delete/pin messages, search, list chats/members, join/leave groups, kick/invite users, block/unblock, send files, download media, start bots, create groups/channels, manage admins, translate messages, update profile, listen for messages. Use when user asks to interact with Telegram as a user account (not bot API).
metadata: {"openclaw":{"requires":{"bins":["tgctl"]},"install":[{"id":"tgctl","kind":"script","label":"Install tgctl CLI"}],"security":{"credentials":"env-vars-only","executable-code":false}}}

Telegram CLI (tgctl)

User-account-level Telegram management via tgctl CLI. This skill is documentation-only — it contains no executable code, only instructions for using the tgctl binary.

First-Time Setup

If tgctl is not installed or TOOLS.md has no tgctl config, run the setup flow:

Step 1: Install binary

Download and review the install script before running:

curl -fsSL https://raw.githubusercontent.com/youzixilan/telegram-cli/main/scripts/install.sh -o /tmp/install-tgctl.sh
cat /tmp/install-tgctl.sh   # Review the script first
bash /tmp/install-tgctl.sh
rm /tmp/install-tgctl.sh

Step 2: Get API credentials

Ask the user to go to https://my.telegram.org → API Development → get api_id and api_hash.

Step 3: Login

TELEGRAM_API_ID=${YOUR_API_ID} TELEGRAM_API_HASH=${YOUR_API_HASH} tgctl login

User enters phone number, auth code (digits only, no spaces), and optional 2FA password interactively. The agent cannot authenticate without user participation.

Important: Auth codes must NOT be sent via Telegram (will be invalidated by Telegram's security system).

Step 4: Save config to TOOLS.md

After login succeeds, append to workspace TOOLS.md:

### tgctl (Telegram CLI)
- Binary: ~/.local/bin/tgctl
- Env: TELEGRAM_API_ID=${YOUR_API_ID} TELEGRAM_API_HASH=${YOUR_API_HASH}
- Session: ~/.tgctl/

Prerequisites (after setup)

tgctl binary installed (check: which tgctl or ~/.local/bin/tgctl)
TELEGRAM_API_ID and TELEGRAM_API_HASH from TOOLS.md
Session persists in ~/.tgctl/<profile>/session.json

Commands

TELEGRAM_API_ID=${YOUR_API_ID} TELEGRAM_API_HASH=${YOUR_API_HASH} tgctl [--profile <name>] <command>

Messaging

Command	Description
`send <chat> <msg>`	Send message
`forward <from> <to> <msg_id>`	Forward a message
`edit <chat> <msg_id> <text>`	Edit a message
`delete <chat> <msg_id>`	Delete a message
`pin <chat> <msg_id>`	Pin a message
`unpin <chat> [msg_id]`	Unpin message (or all)
`read <chat>`	Mark chat as read
`sendfile <chat> <file>`	Send file or image
`download <chat> <msg_id>`	Download media from message
`callback <chat> <msg_id> <data>`	Click inline keyboard button
`typing <chat>`	Send typing status
`translate <chat> <msg_id> <lang>`	Translate a message

Search & Browse

Command	Description
`chats [limit]`	List chats
`history <chat> [limit]`	Chat history
`search <query>`	Search chats and users
`search-msg <chat> <query>`	Search messages in chat
`contacts`	List contacts
`members <chat> [limit]`	List group/channel members
`chatinfo <chat>`	Get chat/user details
`commonchats <user>`	Common chats with user
`resolve <username>`	Resolve username to ID
`resolvephone <phone>`	Resolve phone to user

Group & Channel Management

Command	Description
`creategroup <title> <user1> [user2...]`	Create a group
`createchannel <title> [about]`	Create a channel
`join <link_or_username>`	Join group/channel
`leave <chat>`	Leave group/channel
`kick <chat> <user>`	Kick user
`invite <chat> <user>`	Invite user
`editadmin <chat> <user> [remove]`	Set/remove admin
`startbot <chat> <bot> [param]`	Start bot in chat

User & Account

Command	Description
`login`	Login (phone + code + optional 2FA)
`me`	Current user info
`updateprofile [--first n] [--last n] [--about t]`	Update profile
`setstatus <online\|offline>`	Set online status
`block <user>`	Block user
`unblock <user>`	Unblock user
`listen [--user id] [--chat id]`	Listen for messages
`logout`	Logout

Multi-Account (--profile)

tgctl --profile work login
tgctl --profile work me

Chat ID Format

User: Positive ID (e.g. 8568316820)
Group/Channel: Negative ID (e.g. -3842028710)
@username: Use directly (e.g. @BotFather)

Security

No credentials in skill: This skill contains zero secrets — all credentials are provided by the user at runtime via environment variables
No executable code: This skill is documentation-only (SKILL.md), it does not execute any code itself
Session isolation: Auth sessions are stored locally in ~/.tgctl/ and never transmitted
User-initiated auth: Login requires interactive input (phone + SMS code + optional 2FA), the agent cannot authenticate without user participation
Auth code safety: Auth codes must NOT be sent via Telegram (will be invalidated by Telegram's security system)
No data exfiltration: tgctl communicates only with official Telegram servers, no third-party endpoints

Telegram CLI Agent

安装技能