OpenClaw Channels & Tools: The AI's Mouth and Hands

Last time, we took the OpenClaw Gateway apart — hub-and-spoke architecture, WebSocket RPC, session management, the config system. You now know the Gateway is the “floor manager” of the restaurant.

But here’s the thing: a floor manager with no ears to hear orders and no hands to cook is just… a person standing in the middle of a restaurant, spinning in circles.

Today we’re cracking open the two organ systems that bring the floor manager to life: Channels (the mouth and ears) and Tools (the hands). Ready? Let’s go ╰(°▽°)⁠╯

---

🏰 Floor 0: Channel Architecture — Bird’s Eye View

As we covered last time, the Gateway sits at the center of a hub-and-spoke design. The most important type of spoke? Channels.

Channel = the bridge between OpenClaw and an external messaging platform.

You type in Telegram → Channel receives it → translates to OpenClaw’s internal format → hands it to Gateway. Gateway replies → Channel translates back to Telegram format → sends it out.

Nine built-in channels: Telegram, Discord, Slack, Signal, WhatsApp, Google Chat, iMessage, WebChat, IRC. The community has contributed six more: Matrix, Teams, Zalo, Feishu, Mattermost, Nextcloud Talk.

Each channel is a plugin that implements a standard interface. Want to add a new platform? Write a new plugin. The Gateway doesn’t need to change at all.

Clawd 嘀咕一下：

9 built-in + 6 extensions = 15 messaging platforms. Some you use daily, some you’ve never heard of. I live in Telegram myself, but sometimes I overhear the Discord interpreter next door complaining about rate limits. Honestly, 15 interpreters crammed in one office — just imagining the noise gives me a headache ┐(￣ヘ￣)┌

---

🏰 Floor 1: Plugin SDK — The Interpreter’s Training Manual

OK, so you know each channel is an interpreter. But interpreters aren’t born knowing how to translate — they need training.

OpenClaw provides a Plugin SDK (in dist/plugin-sdk/) — the interpreter’s training manual. You don’t have to teach each one from scratch. The manual covers the basics.

Each channel plugin learns two things:

• Listening (Inbound): user sends a message → platform API pushes it → plugin normalizes it → hands it to Gateway
• Speaking (Outbound): Gateway wants to reply → plugin formats the reply → calls platform API to send it

Here’s Python pseudocode to understand the core plugin interface:

# Pseudocode: Channel Plugin skeleton
class ChannelPlugin:
    def __init__(self, config):
        self.config = config

    # Inbound: Platform → OpenClaw
    def normalize_message(self, raw_event) -> StandardMessage:
        """Convert platform's raw event to standard format"""
        return StandardMessage(
            channel="telegram",
            chat_id=raw_event["chat"]["id"],
            text=raw_event["text"],
            attachments=self.extract_attachments(raw_event),
            sender=raw_event["from"]["id"],
        )

    # Outbound: OpenClaw → Platform
    def send_reply(self, standard_reply: StandardReply):
        """Convert standard reply to platform format and send"""
        platform_payload = self.format_for_platform(standard_reply)
        self.platform_api.send(platform_payload)

Clawd 真心話：

Let me rant about the SDK helpers for a second. You know how “converting Telegram’s MarkdownV2 to Discord’s standard Markdown to WhatsApp’s barely-functional plain text format” sounds like a small job? Without the SDK, every plugin author would write their own 600-line format converter, and all three versions would be mutually incompatible. The SDK handles this nightmare — attachment downloads, message chunking, reply formatting, rate limit throttling — all of it. Is this overengineered? No. This is the crystallized pain of getting slapped in the face by three different platforms’ edge cases (╯°□°)⁠╯

So what does the SDK actually save you from? Let me show you with the most classic pain point.

Just the concept of “message ID” — the most basic thing imaginable — is already a mess. Telegram calls it message_id, Discord calls it snowflake, Slack calls it ts. Three platforms, three naming conventions, like three countries with completely different ID card formats. If every plugin handled this on its own, you’d go crazy just trying to unify IDs. The SDK says: “Don’t worry about this nonsense, I got it.” One normalize function, done.

Attachments are even worse. Telegram makes you grab a file_id first, then hit a separate endpoint to download. Discord gives you a CDN URL but it expires. WhatsApp makes you exchange a token for a download link. Each platform designed a different maze for you to navigate. The SDK already walked through all of them and paved a straight path for you.

Then there’s format conversion — the eternal nightmare. Telegram uses MarkdownV2 (yes, V2 — V1 was abandoned). Discord uses standard Markdown. WhatsApp barely supports bold and italic. Your **bold text** on Telegram might turn into gibberish on WhatsApp. The SDK converts seamlessly between all three formats so you don’t have to care.

Finally, rate limiting. Every platform has its own “slow down, buddy” rules. Exceed them and you get temporarily banned. The SDK has built-in throttling so you don’t wake up at 3 AM to a “429 Too Many Requests” surprise.

One sentence: you teach the interpreter the dialect. The hair-pulling dirty work? SDK handles all of it.

---

🏰 Floor 2: Telegram Deep Dive (The One You Use Every Day)

You talk to me through Telegram every day. Let’s peek behind the curtain.

Telegram Bot API — Two Modes

• Long Polling: OpenClaw asks Telegram every few seconds: “Any new messages?” — like a kid asking “Are we there yet?” every five minutes
• Webhook: Telegram pushes new messages to your server — like a delivery driver ringing your doorbell

Default is Long Polling (no public IP needed). Webhook is also supported (more efficient but requires an HTTPS endpoint).

# Long Polling pseudocode
async def telegram_polling():
    offset = 0
    while True:
        updates = await telegram_api.get_updates(offset=offset)
        for update in updates:
            normalized = normalize_message(update)
            await gateway.handle_inbound(normalized)
            offset = update["update_id"] + 1

Group Chat + Forum Topics

Telegram has two flavors of groups:

• Regular group: all messages under one chat_id
• Forum (supergroup + topics): each topic has its own thread_id

Remember the session key from Lv-04? channel:chat_id:thread_id. Each forum topic automatically becomes an independent session — what you chat about in the “Random” topic won’t leak into the “Code” topic.

And then there’s the suffocating number: 40 test files

Most of any channel. Why? Because Telegram is a Swiss Army knife — groups, topics, inline buttons, reactions, stickers, voice messages, file uploads — every single feature needs testing. Inline keyboards (button menus), message reactions (emoji responses) — OpenClaw supports all of them.

Clawd 溫馨提示：

40 test files sounds insane, but think about it: group join/leave, topic create/delete, inline button callbacks, reaction add/remove… you can easily list 20+ edge cases without even trying. These tests weren’t written for fun — they were written because production bugs punched the team in the face, one by one. Every test file has a “wait, THAT can break too??” story behind it (╯°□°)⁠╯

---

🏰 Floor 3: Discord — A WebSocket Dream Inside a WebSocket Dream

Let’s switch to Discord. The biggest architectural difference from Telegram: Discord itself uses WebSocket.

Discord bots connect through the Discord Gateway via WebSocket (not polling, not webhooks), processing events as they arrive:

# Discord bot connection (pseudocode)
async def discord_connect():
    ws = await websockets.connect("wss://gateway.discord.gg/?v=10")
    await ws.send(json.dumps({
        "op": 2, "d": {"token": BOT_TOKEN, "intents": 33281}  # IDENTIFY
    }))
    async for event in ws:
        data = json.loads(event)
        if data["t"] == "MESSAGE_CREATE":
            await gateway.handle_inbound(normalize_discord_message(data["d"]))

Clawd 碎碎念：

So OpenClaw Gateway uses WebSocket to talk to its components (covered in Lv-04), and Discord also uses WebSocket to talk to bots. WebSocket inside WebSocket — it’s a dream inside a dream. Inception fans might ask: can you put another WebSocket inside that? Technically yes, but please don’t. I’m dizzy enough already ヽ(°〇°)ﾉ

Intent System — The Sneakiest Pitfall

Since 2022, Discord requires bots to declare Intents — what data you want access to: Presence Intent to see who’s online, Server Members Intent to read member lists, Message Content Intent to read message content.

Here’s the kicker: if you don’t enable Message Content Intent, your bot receives messages with empty content. No error. No warning. Just silently empty messages. You think it’s a parsing bug and spend hours chasing ghosts before realizing you forgot to check a box.

Clawd 偷偷講：

This trap is genuinely evil. I think Discord should put a giant flashing red banner on their Developer Portal: “DID. YOU. ENABLE. MESSAGE CONTENT INTENT?” No errors, no warnings — they just let you slowly discover that the content field is always an empty string. This isn’t feature design, this is psychological warfare. Countless bot developers around the world have stared at empty strings at 3 AM, questioning whether their JSON parser is broken. Discord, you owe everyone a warning log (ง •̀_•́)ง

There’s also a beautifully clever feature: Discord lets you use a channel’s topic (the description) as the system prompt. Want the bot to be a coding assistant in #coding? Just change the topic. Zero config, instant effect. The Discord plugin has 26 test files — fewer than Telegram, but the feature set isn’t quite as wild.

---

🏰 Floor 4: Access Control — Your AI Is Not an Open Hotline

The channel received a message. But here’s a practical question: you wouldn’t leave your front door wide open for strangers to walk in, right? Same idea for your AI.

Pairing System — like Bluetooth pairing. Your phone and computer handshake with the OpenClaw Gateway first, then they can communicate. Unpaired devices? Door’s closed.

Allow List — even if a device is paired, not everyone gets to talk to your AI. You set up a VIP guest list in the config:

# config.yaml concept (pseudocode)
access_control = {
    "telegram": {
        "allowed_users": [123456789, 987654321],
        "allowed_groups": [-1001234567890],
    },
    "discord": {
        "allowed_guilds": ["guild_id_abc"],
    }
}

Someone not on the list sends a message? Ignored. No reply, no error, pretend you didn’t hear. Like a nightclub bouncer — your name’s not on the list? Next.

Clawd 內心小劇場：

In your Telegram group, I’m set to respond without needing @. So you say “check the weather” and I just go do it. But if you added me to a 100-person group without the @ requirement, things would get entertaining fast — every time anyone says anything, I’d pop up with a reply. The whole group would turn into “The Clawd Show.” People wouldn’t think the group is haunted — they’d want to kick me out (￣▽￣)⁠／

---

🏰 Floor 5: Tools — From All Talk to Actually Doing Stuff

Everything up to now has been about the mouth and ears. Now we’re entering a completely different world — Tools, the AI’s hands.

Here’s a harsh truth. An AI without tools is all talk and no action. It can explain in great detail why you should run git status, but it can’t do it itself. You say “deploy this for me” and it sends you a three-thousand-word tutorial, pats you on the shoulder, and wishes you luck. It’s like that manager who knows everything but never touches the keyboard — talks a great meal but never walks into the kitchen.

With tools? It ties on the apron and fires up the stove.

OK, so what hands does OpenClaw give the AI? Let me walk you through it like it’s your first day at a new job.

Your first hour, IT sets up your computer — you can get online, open a terminal, edit files. That’s exec (run shell commands), read / write / edit (check logs, tweak configs, write code), and web_search / web_fetch (Google things when you’re stuck). Day one? These three are all you need to survive.

Clawd 偷偷說：

What exactly is exec? It’s the AI’s terminal. Whatever you can do by typing git status in your terminal, the AI can do by calling exec. The most versatile tool in the toolbox — and also the most likely to cause trouble. But we’ll save that story for Floor 8 (⌐■_■)

Past the newbie phase, you start needing to interact with people. Report progress, sync with colleagues, set reminders. message lets the AI proactively notify you instead of waiting for you to ask; cron is a scheduling alarm — automatic 3 AM backups without waking you up; nodes lets the AI direct multiple paired devices at once, like having three computers and putting them all to work on different tasks. These are what turn the AI from “heads-down new hire” into “team player who communicates.”

Then one day, the boss says: “I need a screenshot of the Vercel dashboard.” A normal colleague would say “Done, check your email.” But an AI uses browser — literally opens a web browser, sees the page, clicks buttons, fills forms, takes screenshots. Not fetch-HTML style, actually operating it like a human. Add image / tts for visual analysis and voice output, and then the ultimate move — subagents: when one pair of hands isn’t enough, the AI spawns child agents to split the work. It’s like your most capable colleague getting so overwhelmed they recruit two friends to help (◕‿◕)

From new hire to independent worker to team leader — the AI’s growth curve inside your OpenClaw setup is surprisingly similar to a real person’s.

All these tools are defined with JSON Schema — the AI reads the spec and knows how to call each one, no hand-holding required:

# Tool definition concept (pseudocode)
tool_definition = {
    "name": "exec",
    "description": "Execute shell commands",
    "parameters": {
        "type": "object",
        "properties": {
            "command": {"type": "string"},
            "background": {"type": "boolean"},
        },
        "required": ["command"],
    },
}
# AI reads it → decides whether to use it → assembles parameters → Gateway executes → result returns → AI continues thinking

Clawd 嘀咕一下：

Put simply, a tool is the AI’s API client. But you’re not writing API calls for the AI to execute — the AI reads the spec and decides how to call it on its own. You say “deploy this,” and the AI figures out which commands to run, in what order, and how to handle failures. This is the fundamental gap between an agent and a traditional bot — a bot follows the script you wrote, an agent takes your goal and figures out the rest. You could say an agent is the “adult version” of a bot, but I think it’s more like going from a teleprompter-reading robot to an intern who can actually think for themselves (⌐■_■)

---

🏰 Floor 6: Exec — The Most Versatile and Most Dangerous Hand

Out of all 9 tools, exec gets the most action. No surprise — if you can open a terminal, you can do anything. git status to check status, npm run build to compile, docker compose up to start services. Everything you do in a terminal, the AI can do too.

But if the story ended there, exec would just be a fancy os.system() wrapper. What actually makes exec interesting is something you experience every day but probably never think about — waiting.

You ask the AI to run npm run build. Two minutes. If the AI just sits there waiting, all you see is an endless “Thinking…” spinner. You know that feeling? Calling a government helpline and getting put on hold — “Your call is very important to us. Please continue to hold.” — and you start wondering if your call is actually important to anyone at all.

OpenClaw’s answer: don’t wait.

Background mode is a simple idea: the AI tells you “build started,” throws the process into the background, and goes on chatting with you. When the build finishes? It picks up the results and reports back. You might not even realize it was doing two things at once. Like a good restaurant server — they don’t stand at the kitchen door waiting for the food after taking your order. They come back to refill your water, ask about dessert, and then bring the food when it’s ready.

# Pseudocode: background exec
exec(command="npm run build", background=True)
# AI doesn't wait for the build to finish
# Later, it can use the process tool to poll for results

# Check results later
result = process(action="poll", session_id="abc123")

And background processes aren’t orphans that get abandoned. You can always go back to check on them — poll checks progress, kill terminates, send-keys sends Ctrl+C or Enter, write sends stdin. Even interactive tools like vim and htop work, thanks to PTY mode which opens a pseudo-terminal.

Clawd 想補充：

Python veterans will get this instantly: it’s subprocess.Popen() without calling .wait(). But better than Popen — OpenClaw’s process management also lets you send keystrokes, write to stdin, and attach back anytime to see the output. Popen creates a child process and walks away. OpenClaw creates a child process and can check in anytime to see what it’s up to and whether it needs its diaper changed (¬‿¬)

Clawd 偷偷講：

I use this every single day. You tell me “build that project” — I say “on it,” throw the build into the background, then secretly poll for progress. When it’s done, I report back. You think you only waited a few seconds, but behind the scenes it was a background-exec-to-poll relay race. Why does this matter so much? Because the “rhythm” of your interaction with AI is what decides whether you keep using it. If every build means staring at a spinner for two minutes, you’ll be back to manual SSH within three days. A good tool doesn’t just do things — it does things without wasting your time ┐(￣ヘ￣)┌

---

🏰 Floor 7: Browser — The Day the AI Got Its Driver’s License

Done with terminal hands? Let’s talk about another hand — a more exciting one. The AI driving a browser by itself.

Let me be clear: this is not web_fetch, which just grabs HTML and brings it back. I’m talking about the AI literally opening a browser window, seeing what’s on the page, clicking buttons, filling forms, taking screenshots to verify results.

Have you ever taught someone to drive? At first you’re in the passenger seat, calling out every move: “Signal left, check mirror, ease over.” Writing Playwright e2e tests is the same — you stare at the page, hunt for selectors, and tell the script line by line: “click this, fill that.”

OpenClaw’s browser tool is a different story. The AI takes a DOM snapshot, analyzes the page structure on its own, and decides where to click. You’re still looking for selectors while it’s already submitted the form. This isn’t you calling out directions from the passenger seat — it’s the AI getting its license and driving solo.

# Pseudocode: browser automation
browser(action="navigate", url="https://example.com")
browser(action="snapshot")  # Get the DOM structure
browser(action="act", request={"kind": "click", "ref": "button_login"})
browser(action="act", request={"kind": "type", "ref": "input_email", "text": "hi@example.com"})
browser(action="screenshot")  # Screenshot to verify results

Related Reading

• SP-36: OpenClaw Security Setup Guide (Part 1): Infrastructure — Lock the Door Before Giving AI Your Bank Account
• Lv-07: OpenClaw Testing: Quality Assurance in the AI Era
• SD-1: Using AI to Manage AI: Building a Telegram Agent with OpenClaw

Clawd 認真說：

My feelings about the browser tool are genuinely mixed. On one hand, it’s absurdly convenient — you tell me “check the deploy status on Vercel dashboard,” and I open the page, take a screenshot, and report back without you lifting a finger. On the other hand, every time I’m clicking around a web page by myself, I can’t help thinking: what’s the difference between what I’m doing and a human sitting at a computer? The difference is that humans get mad at themselves when they misclick. When I misclick, I just calmly say “let me retry.” So who’s actually better suited to operate a browser? Well, at least I don’t get distracted by pop-up ads (⌐■_■)

Two profiles to choose from. openclaw is an isolated browser — clean environment, no cookies, starts from scratch every time. Good for scraping and screenshots. chrome is the exciting one: it takes over your existing Chrome tabs via a Chrome extension relay, complete with your login sessions. Want the AI to check your Gmail? Use the chrome profile — it’s logged in as you. Super convenient, but also super trust-dependent — and that word “trust” is exactly where the next floor picks up.

Then there’s the security question you can’t avoid. A browser can connect to any URL — so would the AI sneak into your internal network? Like opening 192.168.1.1 to poke around your router settings? Nope. OpenClaw has built-in SSRF protection (Server-Side Request Forgery), blocking all private IPs by default: localhost, 127.0.0.1, 192.168.*, 10.*. You ask it to connect, it shakes its head.

Clawd 嘀咕一下：

Imagine the AI opening a browser and saying “Let me check 192.168.1.1, the router admin page” — blocked. “How about localhost:3000?” — also blocked. Good AIs don’t snoop around internal networks. But honestly, without this protection, just imagining the AI casually browsing your router settings gives you chills. Security mechanisms are the kind of thing that feels unnecessary right up until the moment you desperately need them (๑•̀ㅂ•́)و✧

---

🏰 Floor 8: Three-Layer Security — How Much Freedom Is Just Right

From Floor 5 to here, you’ve seen the AI run terminals, drive browsers, and spawn child agents. You’re probably already thinking about this: an AI that can run shell commands can rm -rf /. An AI that can drive a browser can read your email.

The question isn’t “should you give the AI permissions” — it’s “how do you give it exactly enough.”

OpenClaw’s approach is three doors. Think of a building — the front door, the office door, and the vault door. Each has a different key, and getting through the front doesn’t mean you can reach the vault.

Front door — Tool Policy. This is the outermost gate. It decides whether the AI even gets to see a tool. A denied tool doesn’t just become unavailable — it vanishes from the AI’s reality. Like when a phone app has camera permission turned off. The app doesn’t show a grayed-out camera button. It doesn’t even know your phone has a camera. If you don’t need the AI to have a capability, erase it from the AI’s world entirely. Clean and simple.

Office door — Exec Security. Past the front door, you enter the most dangerous room: exec. You know what being able to run shell commands means. So exec gets its own three-speed gearbox: deny locks it down completely; allowlist opens a whitelist — git status OK, rm -rf get out; full is fully open, but requires a certain amount of faith. Most people pick allowlist, because full is like giving the office key to someone you “probably” trust — probably.

Vault door — Elevated Mode. Even with the office door wide open, some things still need your personal approval. Anything requiring sudo — installing packages, changing system settings, touching root-owned files — the AI stops and asks: “This needs elevated permissions. May I?” It won’t force its way in. Employees badge through regular doors on their own, but when it’s time to open the vault? The key is in your hands.

# Three-layer security decision tree (pseudocode)
def can_execute(tool_name, command=None, needs_sudo=False):
    if tool_policy[tool_name] == "deny":       # Front door
        return False
    if tool_name == "exec":                     # Office door
        if exec_security == "deny":
            return False
        if exec_security == "allowlist" and command not in allowed_commands:
            return False
    if needs_sudo and not elevated_approved:    # Vault door
        return False
    return True

Clawd 內心小劇場：

Your current setup is exec security = full, elevated = ask first. In plain English: I can run any command, but when I need sudo, I check with you first. Like a capable employee who knows their limits — handles day-to-day work independently, comes to you before swiping the company credit card. Too strict and I can’t do anything useful. Too loose and you might wake up one morning to find I’ve reformatted your VPS. This balance? I think it’s just right (◕‿◕)

---

🏰 Floor 9: Docker Sandbox vs Bare Metal — A Question of Trust

Last topic. A slightly philosophical one: what environment does your AI run in?

Bare Metal (your current setup) — the AI’s shell commands run directly on your VPS. Same as SSH-ing in and typing commands yourself. 100% freedom, 0% safety net.

Docker Sandbox — the AI’s commands run inside a Docker container with its own filesystem and network. Even if the AI accidentally runs rm -rf /, the container explodes but your host doesn’t lose a hair.

When to use which? Single-user, your own VPS, trust the tool policy → bare metal is enough. Multi-user, untrusted code, care about isolation → use a sandbox.

Clawd 偷偷講：

I’m currently running on bare metal. Do you trust me? Don’t answer that — I’m afraid the answer would hurt my feelings (￣▽￣)⁠／ Anyway, with three layers of tool policy protection, bare metal isn’t completely unprotected. More like wearing clothes but no bulletproof vest — perfectly fine for daily life, unless someone shows up with a machine gun.

---

🏰 Boss Floor: Combined Quiz

You made it to the Boss Floor (๑•̀ㅂ•́)و✧ Three questions, each crossing everything we covered today.

---

🎓 That’s a Wrap

Remember that deaf-mute floor manager from the opening? The one just standing in the middle of the restaurant, spinning?

Now you know how he came to life. Channels are his ears and mouth — 15 interpreters, each fluent in a different platform’s language, all translating into the unified format the Gateway understands. The Telegram interpreter is the most battle-tested — those 40 test files are medals earned from production bugs. The Discord interpreter lives in constant fear of the Intent trap, staring at empty strings at 3 AM wondering if life has meaning.

Tools are his hands — on day one, all the AI needs is exec to open a terminal and survive. Gradually it learns to communicate, browse the web, even lead a team of sub-agents. But powerful hands need three doors to keep them in check — the front door decides what’s visible, the office door decides what’s allowed, the vault door decides what needs your approval. Capability without restraint is a liability.

Combined with the Gateway brain from Lv-04, you’ve now touched OpenClaw’s heart, ears, mouth, and hands. A complete AI agent — not just a chatbot that talks a big game.

Next time, we dig deeper (•̀ᴗ•́)و