diff --git a/docs/users/features/_meta.ts b/docs/users/features/_meta.ts
index 9cf6d403f..0dda77989 100644
--- a/docs/users/features/_meta.ts
+++ b/docs/users/features/_meta.ts
@@ -13,4 +13,5 @@ export default {
   'token-caching': 'Token Caching',
   sandbox: 'Sandboxing',
   language: 'i18n',
+  channels: 'Channels',
 };
diff --git a/docs/users/features/channels/_meta.ts b/docs/users/features/channels/_meta.ts
new file mode 100644
index 000000000..70fadc28f
--- /dev/null
+++ b/docs/users/features/channels/_meta.ts
@@ -0,0 +1,4 @@
+export default {
+  overview: 'Overview',
+  telegram: 'Telegram',
+};
diff --git a/docs/users/features/channels/overview.md b/docs/users/features/channels/overview.md
new file mode 100644
index 000000000..71813981c
--- /dev/null
+++ b/docs/users/features/channels/overview.md
@@ -0,0 +1,98 @@
+# Channels
+
+Channels let you interact with a Qwen Code agent from messaging platforms like Telegram, instead of the terminal. You send messages from your phone or desktop chat app, and the agent responds just like it would in the CLI.
+
+## How It Works
+
+When you run `qwen channel start <name>`, Qwen Code:
+
+1. Reads the channel configuration from your `settings.json`
+2. Spawns an agent process using the [Agent Client Protocol (ACP)](../../developers/architecture)
+3. Connects to the messaging platform (e.g., Telegram) and starts listening for messages
+4. Routes incoming messages to the agent and sends responses back to the chat
+
+Each channel runs as a long-lived process that bridges a messaging platform to a Qwen Code agent.
+
+## Quick Start
+
+1. Set up a bot on your messaging platform (see the channel-specific guide, e.g., [Telegram](./telegram))
+2. Add the channel configuration to `~/.qwen/settings.json`
+3. Run `qwen channel start <name>`
+
+## Configuration
+
+Channels are configured under the `channels` key in `settings.json`. Each channel has a name and a set of options:
+
+```json
+{
+  "channels": {
+    "my-channel": {
+      "type": "telegram",
+      "token": "$MY_BOT_TOKEN",
+      "senderPolicy": "allowlist",
+      "allowedUsers": ["123456789"],
+      "sessionScope": "user",
+      "cwd": "/path/to/working/directory",
+      "instructions": "Optional system instructions for the agent."
+    }
+  }
+}
+```
+
+### Options
+
+| Option         | Required | Description                                                                  |
+| -------------- | -------- | ---------------------------------------------------------------------------- |
+| `type`         | Yes      | Channel type: `telegram` (more coming soon)                                  |
+| `token`        | Yes      | Bot token. Supports `$ENV_VAR` syntax to read from environment variables     |
+| `senderPolicy` | No       | Who can talk to the bot: `allowlist` (default), `open`, or `pairing`         |
+| `allowedUsers` | No       | List of user IDs allowed to use the bot (when `senderPolicy` is `allowlist`) |
+| `sessionScope` | No       | How sessions are scoped: `user` (default), `thread`, or `single`             |
+| `cwd`          | No       | Working directory for the agent. Defaults to the current directory           |
+| `instructions` | No       | Custom instructions prepended to the first message of each session           |
+
+### Sender Policy
+
+Controls who can interact with the bot:
+
+- **`allowlist`** (default) — Only users listed in `allowedUsers` can send messages. Others are silently ignored.
+- **`open`** — Anyone can send messages. Use with caution.
+- **`pairing`** — (Coming soon) New users go through a pairing flow before they can chat.
+
+### Session Scope
+
+Controls how conversation sessions are managed:
+
+- **`user`** (default) — One session per user. All messages from the same user share a conversation.
+- **`thread`** — One session per thread/topic. Useful for group chats with threads.
+- **`single`** — One shared session for all users. Everyone shares the same conversation.
+
+### Token Security
+
+Bot tokens should not be stored directly in `settings.json`. Instead, use environment variable references:
+
+```json
+{
+  "token": "$TELEGRAM_BOT_TOKEN"
+}
+```
+
+Set the actual token in your shell environment or in a `.env` file that gets loaded before running the channel.
+
+## Slash Commands
+
+Channels support slash commands. Some are handled locally by the adapter:
+
+- `/start` — Welcome message
+- `/help` — List available commands
+- `/reset` — Reset your session and start fresh
+
+All other slash commands (e.g., `/compress`, `/summary`) are forwarded to the agent.
+
+## Running
+
+```bash
+qwen channel start my-channel
+```
+
+The bot runs in the foreground. Press `Ctrl+C` to stop.
diff --git a/docs/users/features/channels/telegram.md b/docs/users/features/channels/telegram.md
new file mode 100644
index 000000000..236a597ff
--- /dev/null
+++ b/docs/users/features/channels/telegram.md
@@ -0,0 +1,85 @@
+# Telegram
+
+This guide covers setting up a Qwen Code channel on Telegram.
+
+## Prerequisites
+
+- A Telegram account
+- A Telegram bot token (see below)
+
+## Creating a Bot
+
+1. Open Telegram and search for [@BotFather](https://t.me/BotFather)
+2. Send `/newbot` and follow the prompts to choose a name and username
+3. BotFather will give you a bot token — save it securely
+
+## Finding Your User ID
+
+To use `senderPolicy: "allowlist"`, you need your Telegram user ID (a numeric ID, not your username).
+
+The easiest way to find it:
+
+1. Search for [@userinfobot](https://t.me/userinfobot) on Telegram
+2. Send it any message — it will reply with your user ID
+
+## Configuration
+
+Add the channel to `~/.qwen/settings.json`:
+
+```json
+{
+  "channels": {
+    "my-telegram": {
+      "type": "telegram",
+      "token": "$TELEGRAM_BOT_TOKEN",
+      "senderPolicy": "allowlist",
+      "allowedUsers": ["YOUR_USER_ID"],
+      "sessionScope": "user",
+      "cwd": "/path/to/your/project",
+      "instructions": "You are a concise coding assistant responding via Telegram. Keep responses short."
+    }
+  }
+}
+```
+
+Set the bot token as an environment variable:
+
+```bash
+export TELEGRAM_BOT_TOKEN=<your-token-from-botfather>
+```
+
+Or add it to a `.env` file that gets sourced before running.
+
+## Running
+
+```bash
+qwen channel start my-telegram
+```
+
+Then open your bot in Telegram and send a message. You should see "Working..." appear immediately, followed by the agent's response.
+
+## Tips
+
+- **Keep instructions concise-focused** — Telegram has a 4096-character message limit. Adding instructions like "keep responses short" helps the agent stay within bounds.
+- **Use `sessionScope: "user"`** — This gives each user their own conversation. Use `/reset` to start fresh.
+- **Restrict access** — Use `senderPolicy: "allowlist"` with your user ID to prevent unauthorized access. The bot silently ignores messages from users not on the list.
+
+## Message Formatting
+
+The agent's markdown responses are automatically converted to Telegram-compatible HTML. Code blocks, bold, italic, links, and lists are all supported.
+
+## Troubleshooting
+
+### Bot doesn't respond
+
+- Check that the bot token is correct and the environment variable is set
+- Verify your user ID is in `allowedUsers` if using `senderPolicy: "allowlist"`
+- Check the terminal output for errors
+
+### "Sorry, something went wrong processing your message"
+
+This usually means the agent encountered an error. Check the terminal output for details.
+
+### Bot takes a long time to respond
+
+The agent may be running multiple tool calls (reading files, searching, etc.). The "Working..." indicator shows while the agent is processing. Complex tasks can take a minute or more.