qwen-code/docs/developers/channel-plugins.md

Channel Plugin Developer Guide

A channel plugin connects Qwen Code to a messaging platform. It's packaged as an extension and loaded at startup. For user-facing docs on installing and configuring plugins, see Plugins.

How It Fits Together

Your plugin sits in the Platform Adapter layer. You handle platform-specific concerns (connecting, receiving messages, sending responses). ChannelBase handles everything else (access control, session routing, prompt queuing, slash commands, crash recovery).

Your Plugin  →  builds Envelope  →  handleInbound()
ChannelBase  →  gates → commands → routing → ChannelAgentBridge.prompt()
ChannelBase  →  calls your sendMessage() with the agent's response

ChannelAgentBridge is the adapter-facing bridge contract. The current standalone qwen channel start path provides an AcpBridge, but plugin code should type constructor parameters as ChannelAgentBridge so the same adapter can run behind other bridge implementations later.

Migration note for existing TypeScript plugins: if your adapter constructor or factory explicitly types bridge as AcpBridge, change that annotation to ChannelAgentBridge and keep using only the methods exposed by that contract. JavaScript plugins are unaffected at runtime, and standalone qwen channel start still passes the current AcpBridge implementation.

Runtime Modes

The same plugin adapter can be hosted by either channel runtime:

• qwen channel start [name] is the standalone ACP-backed service. It still uses AcpBridge and remains the stable command for running channels outside a daemon.
• qwen serve --channel <name> and repeatable --channel flags start experimental daemon-managed channel workers. Named channels are grouped by owning workspace, with one worker per owning runtime. --channel all intentionally starts only the primary workspace's configured channels. Workers are owned by qwen serve, connect to that daemon through the SDK, and pass adapters a ChannelAgentBridge facade backed by DaemonChannelBridge.

Daemon-managed channels inherit the daemon's lifecycle and status reporting. They are intentionally out-of-process so adapter or platform SDK failures do not crash the daemon. Every named channel must resolve to exactly one registered, trusted workspace; its worker receives that runtime's canonical cwd and environment overlay. A user/system channel with no cwd is ambiguous when several workspaces are registered, while a channel in a workspace-local settings file belongs to that workspace by default. --channel all remains primary-only and cannot be combined with named selections.

The Plugin Object

Your extension entry point exports a plugin conforming to ChannelPlugin:

import type { ChannelPlugin } from '@qwen-code/channel-base';
import { MyChannel } from './MyChannel.js';

export const plugin: ChannelPlugin = {
  channelType: 'my-platform', // Unique ID, used in settings.json "type" field
  displayName: 'My Platform', // Shown in CLI output
  requiredConfigFields: ['apiKey'], // Validated at startup (beyond standard ChannelConfig)
  createChannel: (name, config, bridge, options) =>
    new MyChannel(name, config, bridge, options),
};

The Channel Adapter

Extend ChannelBase and implement three methods:

import { ChannelBase } from '@qwen-code/channel-base';
import type {
  ChannelBaseOptions,
  ChannelAgentBridge,
  ChannelConfig,
  Envelope,
  SessionTarget,
} from '@qwen-code/channel-base';

export class MyChannel extends ChannelBase {
  constructor(
    name: string,
    config: ChannelConfig,
    bridge: ChannelAgentBridge,
    options?: ChannelBaseOptions,
  ) {
    super(name, config, bridge, options);
  }

  async connect(): Promise<void> {
    // Connect to your platform, register message handlers
    // When a message arrives:
    const envelope: Envelope = {
      channelName: this.name,
      senderId: '...', // Stable, unique platform user ID
      senderName: '...', // Display name
      chatId: '...', // Chat/conversation ID (distinct for DMs vs groups)
      text: '...', // Message text (strip @mentions)
      isGroup: false, // Accurate — used by GroupGate
      isMentioned: false, // Accurate — used by GroupGate
      isReplyToBot: false, // Accurate — used by GroupGate
    };
    this.handleInbound(envelope);
  }

  async sendMessage(chatId: string, text: string): Promise<void> {
    // Format markdown → platform format, chunk if needed, deliver
  }

  disconnect(): void {
    // Clean up connections
  }
}

Most adapters should pass options through unchanged. If an adapter creates its own SessionRouter and passes that router to super(), set registerBridgeEvents: true in ChannelBaseOptions so ChannelBase still receives toolCall and sessionDied events directly. Leave it unset for routers supplied by the channel gateway.

If your adapter exposes shell-command or BTW side-question behavior, check that the corresponding bridge.shellCommand / bridge.btw method exists before enabling it. Daemon-managed workers omit those optional methods unless the daemon advertises the matching session_shell_command / session_btw capability. These channel-adapter methods cover the existing JSON side-question API. Direct daemon clients that use SSE must separately check session_btw_stream before calling streamSessionBtw; the daemon advertises it only when every registered runtime ACP session bridge implements generateSessionBtwStream. The existing bridge.btw adapter contract does not imply streaming support.

The Envelope

The normalized message object you build from platform data. The boolean flags drive gate logic, so they must be accurate.

Field	Type	Required	Notes
channelName	string	Yes	Use this.name
senderId	string	Yes	Must be stable across messages (used for session routing + access control)
senderName	string	Yes	Display name
chatId	string	Yes	Must distinguish DMs from groups
chatName	string	No	Group/conversation name when supplied by the platform
text	string	Yes	Strip bot @mentions
threadId	string	No	For sessionScope: "thread"
messageId	string	No	Platform message ID — useful for response correlation
isGroup	boolean	Yes	GroupGate relies on this
isMentioned	boolean	Yes	GroupGate relies on this
isReplyToBot	boolean	Yes	GroupGate relies on this
referencedText	string	No	Quoted message — prepended as context
imageBase64	string	No	Base64-encoded image (legacy — prefer attachments)
imageMimeType	string	No	e.g., image/jpeg (legacy — prefer attachments)
attachments	Attachment[]	No	Structured media attachments (see below)

Attachments

Use the attachments array for images, files, audio, and video. handleInbound() resolves them automatically: images with base64 data are sent to the model as vision input, files with a filePath get their path appended to the prompt so the agent can read them.

interface Attachment {
  type: 'image' | 'file' | 'audio' | 'video';
  data?: string; // base64-encoded data (images, small files)
  filePath?: string; // absolute path to local file (large files saved to disk)
  mimeType: string; // e.g. 'application/pdf', 'image/jpeg'
  fileName?: string; // original file name from the platform
}

Example — handling a file upload in your adapter:

import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

const buf = await downloadFromPlatform(fileId);
const dir = join(tmpdir(), 'channel-files');
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
const filePath = join(dir, fileName);
writeFileSync(filePath, buf);

envelope.attachments = [
  {
    type: 'file',
    filePath,
    mimeType: 'application/pdf',
    fileName,
  },
];

The legacy imageBase64/imageMimeType fields still work for backwards compatibility but attachments is preferred for new code.

Extension Manifest

Your qwen-extension.json declares the channel type. The key must match channelType in your plugin object:

{
  "name": "my-channel-extension",
  "version": "1.0.0",
  "channels": {
    "my-platform": {
      "entry": "dist/index.js",
      "displayName": "My Platform Channel"
    }
  }
}

Optional Extension Points

Custom slash commands — register in your constructor:

this.registerCommand('mycommand', async (envelope, args) => {
  await this.sendMessage(envelope.chatId, 'Response');
  return true; // handled, don't forward to agent
});

Working indicators — override onPromptStart() and onPromptEnd() to show platform-specific typing indicators. These hooks fire only when a prompt actually begins processing — not for buffered messages (collect mode) or gated/blocked messages:

protected override onPromptStart(chatId: string, sessionId: string, messageId?: string): void {
  this.platformClient.sendTyping(chatId); // your platform API
}

protected override onPromptEnd(chatId: string, sessionId: string, messageId?: string): void {
  this.platformClient.stopTyping(chatId);
}

Tool call hooks — override onToolCall() to display agent activity (e.g., "Running shell command...").

Streaming hooks — override onResponseChunk(chatId, chunk, sessionId, segment) for per-chunk progressive display (e.g., editing a message in-place). Override onResponseComplete(chatId, fullText, sessionId, segment) to customize final delivery. In daemon-managed named-task mode, segment.sourceLabel is immutable delivery metadata for that segment. Render it once on each independently visible message or card, including a separately visible final response, but do not add it to raw buffers or model text. Clear adapter-owned segment state from onOutputSegmentEnd().

Named-task attribution — sendThreadMessage(chatId, threadId, text, sourceLabel) receives the same optional plain-text label for one-shot and proactive delivery boundaries. The default implementation handles plain messages. Adapters that override delivery, split messages, emit cards, or provide fallback sends must repeat the label at every independently visible boundary, escape only the label for the target markup dialect, and include its rendered size in platform limits. Run no-reply checks, media-marker projection, audit hashing, transcript persistence, and retry-body capture against the raw response before presentation; if delivery is persisted for restart-safe retry, persist the captured label separately.

Interactive ChannelUserInputRequestContext also carries sourceLabel. Cards, terminal replacements, and plain fallbacks must retain it without weakening the existing request, session, run, owner, and target checks.

Proactive delivery — override supportsProactiveSend() to return true when the adapter can send without an active inbound request. ChannelBase uses this capability for persistent channel loops, webhook tasks, background-agent results, and daemon delivery. The default target policy rejects threaded targets; override the protected target checks only for target shapes your platform can deliver safely:

override supportsProactiveSend(): boolean {
  return true;
}

protected override supportsProactiveTarget(target: SessionTarget): boolean {
  return target.threadId === undefined;
}

protected override async pushProactive(
  target: SessionTarget,
  text: string,
  sourceLabel?: string,
): Promise<void> {
  await this.sendThreadMessage(
    target.chatId,
    target.threadId,
    text,
    sourceLabel,
  );
}

Use supportsProactiveDeliveryTarget() when generic daemon delivery accepts a different target shape, and supportsProactiveWebhookTarget() when webhook delivery differs from loops and background results. Keep unsupported targets rejected rather than falling back to another conversation.

An adapter that streams chunks from onResponseChunk must also consult isProactivePromptTurn(sessionId): it is true for loop and webhook turns, whose result ChannelBase delivers once, in full, through pushProactive and for which it never calls onResponseComplete. Posting progressive output for those turns would post the same text twice, so a chunk-flushing sink must suppress them.

Media — populate envelope.attachments with images/files. See Attachments above.

Reference Implementations

• Plugin example (packages/channels/plugin-example/) — minimal WebSocket-based adapter, good starting point
• Telegram (packages/channels/telegram/) — full-featured: images, files, formatting, typing indicators
• DingTalk (packages/channels/dingtalk/) — stream-based with rich text handling