tg-canvas

What This Skill Does

The tg-canvas skill provides a high-performance bridge between OpenClaw AI agents and the Telegram ecosystem. At its core, it acts as a real-time canvas engine, allowing agents to push dynamically rendered HTML, markdown, or A2UI content directly into a Telegram Mini App. Beyond content rendering, it features a robust, JWT-authenticated server-side PTY (pseudo-terminal) which grants an agent direct bash access to the host machine. The skill is designed with a security-first architecture, requiring mandatory Telegram initData verification and restricting access to a predefined whitelist of Telegram User IDs. By utilizing cloudflared for secure HTTPS tunneling, it ensures that your agent interactions remain encrypted and protected from unauthorized public access.

Installation

1. Ensure you have Node.js 18+ and cloudflared installed on your host system.
2. Clone the skill repository and configure your environment variables: BOT_TOKEN, ALLOWED_USER_IDS, and JWT_SECRET.
3. Run the setup script to link your Telegram bot: BOT_TOKEN=... MINIAPP_URL=... node scripts/setup-bot.js.
4. Launch the server process using node server.js.
5. Expose your local port 3721 to the public web via: cloudflared tunnel --url http://localhost:3721.
6. For the agent to push content, use the CLI: npm install -g . then execute tg-canvas push --html "<p>Active</p>".

Use Cases

This skill is ideal for AI-driven system administration, where an agent needs to show the status of server processes and execute remediation commands via a shell. It also serves as a portable UI for data visualization, allowing an agent to render charts or tables in the Mini App format. Developers can use the proxy mode to interface with the OpenClaw Control UI, turning their Telegram app into a remote dashboard for agent management.

Example Prompts

1. "Open the terminal in my Telegram canvas and run a disk usage check on the root partition."
2. "Render a summary of my current project tasks in a clean HTML dashboard in the Telegram Mini App."
3. "Update the canvas with a markdown status report of the active agent connections."

Tips & Limitations

Security is paramount: always define ALLOWED_USER_IDS to prevent unauthorized shell access. Remember that the PTY session is volatile—the terminal state is destroyed upon closing the WebSocket. While ENABLE_OPENCLAW_PROXY allows for powerful UI features, leave it disabled (default) unless you specifically require Control UI access. Avoid rendering untrusted external HTML to prevent XSS risks within the Mini App container.