qwen-code Documentation

Technical Documentation: QwenLM/qwen-code

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Why Qwen Code? Copy Chapter

• Agentic out of the box — Auto-Memory, Auto-Skills, SubAgents, Agent Teams, and MCP. Dynamic workflows, zero setup.
• Open-source, inside and out — The framework and the Qwen models are open-source. They evolve together. No vendor lock-in.
• Multi-protocol — Supports OpenAI, Anthropic, Gemini, and Qwen APIs. Any third-party provider or local model (Ollama / vLLM). Switch at runtime.
• Beyond the terminal — IDE plugins, Desktop app, Web UI, SDKs, and chat integrations (Telegram / DingTalk / WeChat / Feishu).

[!TIP]
Qwen Code is actively iterating on itself — using its own agent and models to file issues, submit PRs, review code, and run tests. Powered by the community, driven by AI.

Installation Copy Chapter

Linux / macOS:

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

Windows:

irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

Restart your terminal after installation to ensure environment variables take effect.

NPM / Homebrew

NPM (requires Node.js 22+):

npm install @qwen-code/qwen-code@latest

Homebrew (macOS / Linux):

brew install qwen-code

Quick Start Copy Chapter

Open a terminal in your project and start Qwen Code:

cd /path/to/your-project
qwen

Inside the session, run /auth to configure your provider and API key. Then try:

Explain this repository and show me where to start.

See the Authentication Guide and Settings Reference for detailed setup.

See the terminal interface

How to Use Qwen Code Copy Chapter

Choose the interface that fits your workflow:

For automation and custom integrations:

• Headless — Run qwen -p "..." in scripts, CI/CD, or batch jobs.
• SDKs — Build with TypeScript, Python, or Java.
• Daemon — Run qwen serve to connect clients over HTTP + SSE (ACP). (experimental) Daemon guide.
• Computer Use — Set up native MCP tools or Node REPL + SDK in Qwen Code, Claude Code, or Codex.

SDK example (Python)

import asyncio

from qwen_code_sdk import is_sdk_result_message, query


async def main() -> None:
    result = query(
        "Summarize the repository layout.",
        {
            "cwd": "/path/to/project",
            "path_to_qwen_executable": "qwen",
        },
    )

    async for message in result:
        if is_sdk_result_message(message):
            print(message["result"])


asyncio.run(main())

Capabilities Copy Chapter

If you know Claude Code, you already know Qwen Code — and then some. We've put significant effort into bringing Qwen Code to feature parity with Claude Code, improving both breadth and reliability across the board.

Qwen Code Evaluation Copy Chapter

On SWE-bench Verified, seven Qwen Code versions scored 76.40%–77.80% on average using the same Qwen 3.7 Max model (500 tasks, three trials per version).

Full results and evaluation configuration →

Ecosystem Copy Chapter

• Qwen Code Desktop — Official desktop app for macOS, Windows, and Linux

• AionUi — A modern GUI for command-line AI tools including Qwen Code

• Gemini CLI Desktop — A cross-platform desktop/web/mobile UI for Qwen Code

• qwen-audio-agent — Realtime full-duplex voice frontend for Qwen Code over ACP — talk hands-free with barge-in and a local wake word

• 🦞 Qwen Code Claw — Let other agents (Claude, Codex, etc.) delegate coding tasks to Qwen Code via ACP. Paste this prompt into your agent:

Use Qwen Code as a coding agent. First, fetch and read this skill reference:
https://raw.githubusercontent.com/QwenLM/qwen-code/refs/heads/main/.qwen/skills/qwen-code-claw/SKILL.md
Then follow the instructions inside to install, authenticate, and use Qwen Code via acpx for all coding tasks.

• Aliyun Model Studio CLI — Official CLI for Aliyun's AI platform (bailian-cli). Extends Qwen Code with image/video generation, knowledge retrieval, app orchestration, and model deployment

Privacy Copy Chapter

See the Terms of Service and Privacy Notice, including Chrome extension and Browser Use data handling.

Contributing Copy Chapter

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Acknowledgments Copy Chapter

This project was originally based on Google Gemini CLI v0.8.2. We gratefully acknowledge the Gemini CLI team's excellent work. Starting from Qwen Code v0.1, we stopped syncing with upstream and began independent development as a multi-protocol, multi-platform agent framework with deep integrations for Qwen models and beyond.

Index (`docs/index.md`) Copy Section

Qwen Code Documentation

Welcome to the Qwen Code documentation. Qwen Code is an agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before.

Documentation Sections Copy Chapter

[User Guide](./users/overview) Copy Section

Learn how to use Qwen Code as an end user. This section covers:

• Basic installation and setup
• Common usage patterns
• Features and capabilities
• Configuration options
• Troubleshooting

[Developer Guide](./developers/architecture) Copy Section

Learn how to contribute to and develop Qwen Code. This section covers:

• Architecture overview
• Contributing guidelines
• Core concepts and implementation details
• Tools and development workflow
• Extension and plugin development

Users Overview (`docs/users/overview.md`) Copy Section

Qwen Code overview

Learn about Qwen Code, Qwen's agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before.

Get started in 30 seconds Copy Chapter

Install Qwen Code: Copy Section

The recommended installer uses a standalone archive when one is available for
your platform. If it falls back to npm, Node.js 22 or later with npm must be
available on PATH.

Linux / macOS

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

Windows

irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

[!note]

It's recommended to restart your terminal after installation if qwen is not
immediately available on PATH. If the installation fails, please refer to
Manual Installation in the Quickstart
guide. For offline installation, download a release archive and run the
installer with --archive PATH; keep SHA256SUMS next to the archive.

Start using Qwen Code: Copy Section

cd your-project
qwen

On first launch you'll be prompted to connect a model provider. The menu offers QwenCloud (the official recommended setup), Alibaba ModelStudio, Third-party Providers (built-in providers such as DeepSeek, MiniMax, Z.AI, Kimi, and OpenRouter, connected with an API key), and Custom Provider (a local server, proxy, or unsupported provider). For a QwenCloud key, choose QwenCloud → Token Plan or QwenCloud → Standard API Key and then pick the platform (China or International) — see Authentication. For the Alibaba Cloud Token Plan (intl), choose Alibaba ModelStudio → Token Plan; to use a ModelStudio API key, choose Alibaba ModelStudio → Standard API Key and follow the API setup guide (Beijing / intl). Then let's start with understanding your codebase. Try one of these commands:

what does this project do?

You'll be prompted to log in on first use. That's it! Continue with Quickstart (5 mins) →

[!tip]

See troubleshooting if you hit issues.

[!note]

New VS Code Extension (Beta): Prefer a graphical interface? Our new VS Code extension provides an easy-to-use native IDE experience without requiring terminal familiarity. Simply install from the marketplace and start coding with Qwen Code directly in your sidebar. Download and install the Qwen Code Companion now.

What Qwen Code does for you Copy Chapter

• Build features from descriptions: Tell Qwen Code what you want to build in plain language. It will make a plan, write the code, and ensure it works.
• Debug and fix issues: Describe a bug or paste an error message. Qwen Code will analyze your codebase, identify the problem, and implement a fix.
• Navigate any codebase: Ask anything about your team's codebase, and get a thoughtful answer back. Qwen Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with MCP can pull from external datasources like Google Drive, Figma, and Slack.
• Automate tedious tasks: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI.
• Followup suggestions: Qwen Code predicts what you want to type next and shows it as ghost text. Press Tab to accept, or just keep typing to dismiss.

Why developers love Qwen Code Copy Chapter

• Works in your terminal: Not another chat window. Not another IDE. Qwen Code meets you where you already work, with the tools you already love.
• Takes action: Qwen Code can directly edit files, run commands, and create commits. Need more? MCP lets Qwen Code read your design docs in Google Drive, update your tickets in Jira, or use your custom developer tooling.
• Unix philosophy: Qwen Code is composable and scriptable. tail -f app.log | qwen -p "Slack me if you see any anomalies appear in this log stream" works. Your CI can run qwen -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review".

Users Quickstart (`docs/users/quickstart.md`) Copy Section

Quickstart

👏 Welcome to Qwen Code!

This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Qwen Code for common development tasks.

Before you begin Copy Chapter

Make sure you have:

• A terminal or command prompt open
• A code project to work with
• An API key or Token Plan subscription from 千问AI平台 / QwenCloud (China / International) — the recommended setup — or an API key from Alibaba Cloud ModelStudio (Beijing / intl), or an Alibaba Cloud Token Plan (Beijing / intl) subscription

Step 1: Install Qwen Code Copy Chapter

To install Qwen Code, use one of the following methods:

Quick Install (Recommended) Copy Section

Linux / macOS

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

Windows

irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

[!note]

It's recommended to restart your terminal after installation to ensure environment variables take effect.

Manual Installation Copy Section

Prerequisites

Make sure you have Node.js 22 or later installed. Download it from nodejs.org.

NPM

npm install @qwen-code/qwen-code@latest

Homebrew (macOS, Linux)

brew install qwen-code

Step 2: Set up authentication Copy Chapter

When you start an interactive session with the qwen command, you'll be prompted to configure authentication:

# You'll be prompted to set up authentication on first use
qwen

# Or run /auth anytime to change authentication method
/auth

The first-run menu lets you connect a model provider. Choose one of:

• QwenCloud — the recommended setup. Opens a sub-menu:

  • Token Plan: subscription with a monthly Credit quota on a dedicated endpoint (Personal and Team editions).
  • Standard API Key: pay-as-you-go, connect with an existing platform API key.

  Either way you then pick the platform explicitly (China or International), so the UI language never decides your endpoint. See Authentication → Option 1: QwenCloud for details.

• Alibaba ModelStudio — opens a sub-menu:

  • Token Plan: usage-based billing with a dedicated endpoint, aimed at teams and companies. See the Token Plan guide (intl) for setup instructions.
  • Standard API Key: connect with an existing API key from Alibaba Cloud ModelStudio (Beijing / intl). See the API setup guide (Beijing / intl) for details.

• Third-party Providers — choose a built-in provider (DeepSeek, Grok, MiniMax, Z.AI, Kimi, Idealab, ModelScope, OpenRouter, Requesty, and more) and connect with an API key.

• Custom Provider — manually connect a local server, proxy, or unsupported provider.

⚠️ Note: Qwen OAuth was discontinued on April 15, 2026. If you were previously using Qwen OAuth, please switch to one of the methods above.

[!note]

Qwen Code stores its configuration and customizations in .qwen directories: ~/.qwen/ for user-level settings (e.g. settings.json) and global custom commands, and /.qwen/ for project-specific files such as custom commands and summaries.

[!tip]

To configure authentication, start Qwen Code and run /auth. Use /doctor to check your current configuration at any time. See the Authentication page for details.

Step 3: Start your first session Copy Chapter

Open your terminal in any project directory and start Qwen Code:

# optional
cd /path/to/your/project
# start qwen
qwen

You'll see the Qwen Code welcome screen with your session information, recent conversations, and latest updates. Type /help for available commands.

Chat with Qwen Code Copy Chapter

Ask your first question Copy Section

Qwen Code will analyze your files and provide a summary. You can also ask more specific questions:

explain the folder structure

You can also ask Qwen Code about its own capabilities:

what can Qwen Code do?

[!note]

Qwen Code reads your files as needed - you don't have to manually add context. Qwen Code also has access to its own documentation and can answer questions about its features and capabilities.

Make your first code change Copy Section

Now let's make Qwen Code do some actual coding. Try a simple task:

add a hello world function to the main file

Qwen Code will:

1. Find the appropriate file
2. Show you the proposed changes
3. Ask for your approval
4. Make the edit

[!note]

Qwen Code always asks for permission before modifying files. You can approve individual changes or enable "Accept all" mode for a session.

Use Git with Qwen Code Copy Section

Qwen Code makes Git operations conversational:

what files have I changed?

commit my changes with a descriptive message

You can also prompt for more complex Git operations:

create a new branch called feature/quickstart

show me the last 5 commits

help me resolve merge conflicts

Fix a bug or add a feature Copy Section

Qwen Code is proficient at debugging and feature implementation.

Describe what you want in natural language:

add input validation to the user registration form

Or fix existing issues:

there's a bug where users can submit empty forms - fix it

Qwen Code will:

• Locate the relevant code
• Understand the context
• Implement a solution
• Run tests if available

Test out other common workflows Copy Section

There are a number of ways to work with Qwen Code:

Refactor code

refactor the authentication module to use async/await instead of callbacks

Write tests

write unit tests for the calculator functions

Update documentation

update the README with installation instructions

Code review

review my changes and suggest improvements

[!tip]

Remember: Qwen Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there.

Essential commands Copy Chapter

Here are the most important commands for daily use:

See the CLI reference for a complete list of commands.

Pro tips for beginners Copy Chapter

Be specific with your requests

• Instead of: "fix the bug"
• Try: "fix the login bug where users see a blank screen after entering wrong credentials"

Use step-by-step instructions

• Break complex tasks into steps:

1. create a new database table for user profiles
2. create an API endpoint to get and update user profiles
3. build a webpage that allows users to see and edit their information

Let Qwen Code explore first

• Before making changes, let Qwen Code understand your code:

analyze the database schema

build a dashboard showing products that are most frequently returned by our UK customers

Save time with shortcuts

• Press ? to see all available keyboard shortcuts
• Use Tab for command completion
• Press ↑ for command history
• Type / to see all slash commands

Getting help Copy Chapter

• In Qwen Code: Type /help or ask "how do I..."
• Documentation: You're here! Browse other guides
• Community: Join our GitHub Discussion for tips and support

Users Features Channels Overview (`docs/users/features/channels/overview.md`) Copy Section

Channels

Channels let you interact with a Qwen Code agent from messaging platforms like Telegram, WeChat, QQ, DingTalk, WeCom, or Feishu, 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.

Code-hosting platforms (starting with GitHub) and authenticated workspace accounts (starting with DingTalk Workspace) are also supported through channels. Email connects a dedicated mailbox through IMAP and SMTP.

How It Works Copy Chapter

When you run qwen channel start, Qwen Code:

1. Reads channel configurations from your settings.json
2. Spawns a single agent process using the Agent Client Protocol (ACP)
3. Connects to each messaging platform and starts listening for messages
4. Routes incoming messages to the agent and sends responses back to the correct chat

All channels share one agent process with isolated sessions per user. Each channel can have its own working directory, model, and instructions.

Quick Start Copy Chapter

1. Set up a bot or authenticated workspace account (see channel-specific guides: Telegram, WeChat, QQ Bot, DingTalk, DingTalk Workspace, WeCom, WeCom Callback, Feishu, GitHub, Email)
2. Add the channel configuration to ~/.qwen/settings.json
3. Run qwen channel start to start all channels, or qwen channel start <name> for a single channel

Want to connect a platform that isn't built in? See Plugins to add a custom adapter as an extension.

Configuration Copy Chapter

Channels are configured under the channels key in settings.json. Each channel has a name and a set of options:

{
  "channels": {
    "my-channel": {
      "type": "telegram",
      "token": "$MY_BOT_TOKEN",
      "privatePolicy": "allowlist",
      "allowedUsers": ["123456789"],
      "sessionScope": "user",
      "cwd": "/path/to/working/directory",
      "instructions": "Optional system instructions for the agent.",
      "groupPolicy": "disabled",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Options Copy Section

Message Routes Copy Section

Use messageRoutes to run multiple workflows through one Channel connection.
Each key is a case-sensitive message prefix and each value contains instructions
for that route:

{
  "messageRoutes": {
    "/review": "Review the requested pull request.",
    "/QA": "Answer questions about this repository."
  },
  "defaultMessageRoute": "/QA"
}

A prefix must be followed by whitespace and a non-empty message. The longest
matching prefix wins; leading mentions are skipped when matching. The matched prefix is removed before the
message reaches the agent. Route instructions are combined with the Channel's
common instructions on the first turn of each session. Routes use separate
sessions within the configured sessionScope. Existing Channel memory remains
shared at its configured chat/thread scope; routes are not a permissions sandbox.

Without defaultMessageRoute, unmatched chat messages are ignored. To accept
ordinary messages, set it to a key in messageRoutes; those messages keep their
original text and use that route's instructions and session. Empty prefixes and
empty route maps are invalid. Route instructions may be empty. Prefixes and
instructions are trimmed when loading configuration. messageRoutes cannot be
combined with multiSession.

Routing does not grant access: private and group policies still apply. Shared
and agent commands also need a route prefix, for example /QA /help. Messages
without user-authored text and provider-generated system events remain outside
prefix routing.

Private Policy Copy Section

privatePolicy controls private conversations independently of groups:

• disabled — Ignore private messages without creating pairing requests.
• allowlist — Only users listed in the top-level allowedUsers may send private messages.
• pairing — Users in allowedUsers are admitted directly. Other users need a locally approved user pairing. See DM Pairing.
• open — Anyone can send private messages.

New managed channels default to pairing. The deprecated senderPolicy and dmPolicy keys remain supported: an explicit privatePolicy takes precedence; otherwise dmPolicy: "disabled" disables private access, and otherwise senderPolicy supplies the policy (default allowlist). These old keys do not restrict group members. Saving from the editor uses privatePolicy and preserves existing deprecated keys.

Shared-Session Operators Copy Section

In a shared session (sessionScope: "chat_thread" or "single", and group chats under "thread"), some commands affect everyone in the conversation: /approve, /deny, /cancel, /clear, /who, /status, /loop, /btw, the loop tool, and steering an in-flight turn. Only the session's operators may use them; other members' messages queue instead of steering. Sessions that are not shared belong to their own sender, who may always use them.

Set operators to the user IDs allowed to manage shared sessions. Omitted or empty operators grants nobody this role. Private allowlists, user pairing, group pairing, and group member lists never imply operator permissions. Operators must still pass normal conversation admission.

For example, groups: { "*": { "senders": "open" } } with operators: ["alice"] lets every admitted group member start a turn, but only Alice can manage its shared session.

A saved loop is checked against the same rule when it fires, using its creator as the sender, and is disabled if the creator is no longer an operator.

Session Scope Copy Section

Controls how conversation sessions are managed:

• user (default) — One session per user. All messages from the same user share a conversation.
• chat_thread — One session per chat thread/topic, shared by participants in that thread.
• thread — Legacy thread/topic routing retained for existing configurations.
• single — One shared session for all users. Everyone shares the same conversation.

Named Tasks Copy Section

Daemon-managed Channels can retain several named conversations for the same user in one chat:

{
  "channels": {
    "my-channel": {
      "type": "telegram",
      "sessionScope": "user",
      "multiSession": true
    }
  }
}

The catalog is private to the exact channel, chat, and sender. Task names use 1–32 ASCII letters, numbers, underscores, or hyphens, and are unique case-insensitively. Up to eight tasks may be open; closing a task detaches it without deleting its transcript, so selecting it later reopens the exact conversation. Session IDs are never accepted by or shown in chat commands.

Named results identify their originating task: direct chats use [task], while group chats use [sender · task]. Named text permission prompts also show the exact request ID and the corresponding /approve , /approve-always , and /deny commands. The label is presentation-only and is not stored in the model transcript.

One task remains selected to receive the next normal message, but other named tasks may keep running concurrently. /session new <name> shares the configured workspace, while /session new <name> --worktree creates an isolated checkout for that task under the daemon workspace's .qwen/worktrees/ directory. The daemon verifies the persisted worktree owner before reopening the task after a restart; a missing, changed, or foreign ownership record fails closed instead of silently moving the task into the shared workspace. Creating or selecting another task does not cancel or retarget earlier work, and late results retain their originating task label. A busy task cannot be closed, but its active prompt can be cancelled with /session cancel [<name>] through the existing Channel cancellation behavior. Independently queued turns are not cancelled, but in collect dispatch mode any follow-ups buffered behind the cancelled prompt are discarded by that existing behavior. Media preparation is not targeted. Bare permission commands apply only to the selected task, while an explicit request ID can answer an owned inactive task. /clear, /new, and /reset also work on a selected worktree task: the task gets a fresh conversation while its worktree and files are kept. A busy worktree task refuses the reset until its prompt finishes, and a task whose worktree record was damaged reports the failure without touching files. Channel memory remains scoped to the chat rather than to a named task.

This mode is unavailable in standalone qwen channel start, with webhooks, with non-zero channel or group groupHistoryLimit, or with Channel loops. If an enabled loop already exists for that channel, the daemon worker refuses to start until the loop is disabled.

Session Rotation Copy Section

Long-lived routes can start a fresh conversation after a configured limit:

{
  "channels": {
    "my-bot": {
      "type": "dingtalk",
      "sessionScope": "chat_thread",
      "sessionRotation": { "maxTurns": 200, "maxAgeHours": 24 }
    }
  }
}

Either positive bound may be used alone; the first one reached triggers rotation before the next routed message. maxTurns counts messages routed to the session, including messages handled without a model turn. The count and age start persist across restarts. A route with a running or queued message waits for a later idle message to rotate, so steady traffic may pass the configured bound. Rotation clears that route's conversation context, retires its old session, and posts a notice in the triggering chat or thread. With sessionScope: "single", other chats sharing the session do not receive the notice. Omitting sessionRotation preserves ongoing session reuse. Named tasks (multiSession) cannot use this option.

Channel Memory Copy Section

Channel memory stores durable context for one chat or thread. Entries have stable
IDs, so a list response can be used for deterministic follow-up operations.

• 记住：默认使用 staging 环境 is the deterministic form and saves exactly one
  scalar entry for the current chat or thread.
• To save several separate facts in one request, use a natural phrase routed
  through the classifier. For example:
  请记住这三条约定：使用 staging；发布前测试；优先中文回复 creates entries
  that you can manage independently. Exact duplicate facts are skipped and
  reported without creating another entry. Requests containing credential-like
  text are rejected; remove secrets and save the non-sensitive facts separately.
• 查看记忆 lists entries and their stable IDs. Use 查看第 2 页记忆 to view
  a later page, 查看记忆 to view one entry, or a natural filtered
  request such as 只看中文偏好 to list the matching entries.
• 查看刚才那条记忆, 把关于 staging 的记忆改成默认使用 production, and
  忘掉刚才那条 work when the natural reference resolves to exactly one entry.
  Natural updates and removals first show the proposed change. Confirm an
  update with 确认更新记忆 or confirm memory update, or a removal with
  确认删除记忆 or confirm memory removal, within 60 seconds. Exact-ID
  updates and removals remain immediate and do not need confirmation.
• 清空记忆 starts the clear-all confirmation flow; 确认清空记忆 completes
  it.

When a natural inspect, update, or removal request matches multiple entries,
the bot returns the candidate IDs and previews without changing memory. There
is no pending selection for an ambiguous result: retry the request with one
exact ID, such as 忘掉 m-a31f0d82c7e4. Exact-ID operations remain the
deterministic fast path. A natural request with no match reports that no entry
matched.

Pending update, removal, and clear confirmations apply only to the sender and
chat or thread that created them. A newer clear, natural update, or natural
removal proposal replaces an older pending one for that sender and target.
Pending confirmations are discarded when the channel process restarts.

The legacy slash aliases /remember-channel, /channel-memory, and
/forget-channel have been removed. They are no longer channel-memory
commands.

Channel memory follows the channel access gates. Any message accepted by
private access, group admission, group member settings,
pairing, and mention requirements can read, write, update, or clear memory for
that chat or thread. Accepted members of the same group share that group's
target store. Use a group's senders: "allowlist" with its allowedUsers when group memory should be
limited to trusted senders — under senders: "open" every member of an
admitted group shares that group's memory store.

Existing legacy CHANNEL.md memory is migrated automatically to structured
CHANNEL.json storage on the first mutation. Structured memory persists across
standalone channel and daemon-managed channel restarts, and is injected when a
fresh target-scoped session starts, including after /clear.

After that initial injection, each accepted message also recalls up to three
relevant entries for that message. This keeps durable facts available during a
long-running session without adding every stored entry to every turn. Recall is
based on the current message and does not modify the stored memory.

Memory remains keyed to the current chat or thread. It is not injected or
recalled in a sessionScope: single session, because that session is shared
across the whole channel rather than scoped to one target.

Channel memory does not automatically learn facts from normal conversation or
accept 第一个 as confirmation for an ambiguous natural reference. Use a clear
remember request and an exact entry ID when a natural reference is ambiguous.

Token Security Copy Section

Bot tokens should not be stored directly in settings.json. Instead, use environment variable references:

{
  "token": "$TELEGRAM_BOT_TOKEN"
}

Set the actual token in your shell environment or in a .env file that gets loaded before running the channel.

DM Pairing Copy Chapter

When privatePolicy is set to "pairing", unknown senders go through an approval flow:

1. An unknown user sends a message to the bot
2. The bot replies with an 8-character pairing code (e.g., VEQDDWXJ)
3. The user shares the code with you (the bot operator)
4. You approve them via CLI:

qwen channel pairing approve my-channel VEQDDWXJ

Once approved, the user's ID is saved to the channel's workspace-scoped allowlist (~/.qwen/channels/<workspace-scope>/<name>-allowlist.json) and all future messages go through normally. Pairing state is scoped per workspace, so two workspaces using the same channel name keep separate approvals.

Pairing CLI Commands Copy Section

# List pending pairing requests
qwen channel pairing list my-channel

# Approve a request by code
qwen channel pairing approve my-channel <CODE>

Run these from the channel's workspace directory (or pass --cwd <dir>) — pairing state is stored per workspace.

Pairing Rules Copy Section

• Codes are 8 characters, uppercase, using an unambiguous alphabet (no 0/O/1/I)
• Codes expire after 1 hour
• Maximum 3 pending requests per channel at a time, and at most one per sender — additional requests are declined until one expires or is approved
• Users listed in allowedUsers in settings.json skip user pairing; under groupPolicy: "pairing", the group itself must still be approved
• Approved users are stored per workspace in ~/.qwen/channels/<workspace-scope>/<name>-allowlist.json — treat this file as sensitive

Group Chats Copy Chapter

By default, the bot only works in direct messages. To enable group chat support, set groupPolicy to "allowlist", "pairing", or "open".

Group Policy Copy Section

Controls whether the bot participates in group chats at all:

• disabled (default) — The bot ignores all group messages. Safest option.
• allowlist — The bot only responds in groups explicitly listed in groups by chat ID. The "*" key provides default settings but does not act as a wildcard allow.
• pairing — A deliberate mention or reply from an unknown group creates one pairing request for the group. Once approved, members can use the bot subject to the group's senders setting (default open); privatePolicy continues to control direct messages.
• open — The bot responds in all groups it's added to. Use with caution.

Approve a group with the same CLI command used for user pairing. The pending
request identifies the group and the member who initiated it:

qwen channel pairing approve my-channel <CODE>

Group approvals are stored by the group's chat ID in the channel's workspace scope. On GitHub and GitLab the chat ID is the repository/project path, so a rename or transfer detaches the stored approval — re-approve the group after renaming. A repo or project re-created under the same path inherits any stale approval — revoke group approvals after any rename, transfer, or deletion.
An unmentioned message never creates a group pairing request, even when a group
sets requireMention to false; after approval, the configured mention policy
applies normally.

Group pairing requests share the same pending queue as DM pairing requests:
a channel holds at most 3 pending requests overall, and a sender holds at most
one pending request across user and group requests (see
Pairing Rules).

Mention Gating Copy Section

In groups, the bot requires an @mention or a reply to one of its messages by default. This prevents the bot from responding to every message in a group chat.

Configure per-group with the groups setting:

{
  "groups": {
    "*": { "requireMention": true },
    "-100123456": { "requireMention": false }
  }
}

• "*" — Default settings for all groups. Only sets config defaults, not an allowlist entry.
• Group chat ID — Override settings for a specific group. Overrides "*" defaults.
• requireMention (default: true) — When true, the bot only responds to messages that @mention it or reply to one of its messages. When false, the bot responds to all messages (useful for dedicated task groups).

Group Senders Copy Section

Admitted groups allow all members by default. Set senders in groups to restrict members independently of private access:

{
  "privatePolicy": "pairing",
  "groupPolicy": "open",
  "groups": {
    "*": { "senders": "open" },
    "-100123456": { "senders": "allowlist", "allowedUsers": ["alice", "bob"] }
  }
}

• open (default) — Any member of an admitted group may use the bot. Private policy and user pairing have no effect on group members.
• allowlist — only the group's allowedUsers may speak. This list is separate from the channel-level allowedUsers.

All group settings use field-by-field inheritance: the specific group, then "*", then the channel default where applicable, then the built-in default. Empty objects inherit defaults; arrays replace rather than merge, including allowedUsers: []. For example, a group that sets only senders: "allowlist" uses the allowedUsers from "*". Under groupPolicy: "allowlist" a group ID key also admits the group, so a per-group entry there both admits the group and sets its senders.

pairing is deliberately not a senders value: pairing approvals are stored per user, so approving someone through a group message would also unlock their direct messages. Use groupPolicy: "pairing" to admit an entire group instead.

On the github and gitlab channels all inbound traffic is group traffic, so only groupPolicy and group member settings govern admission — see those channels' Security notes before using it on a public repository or project. Under sessionScope: "single" direct messages and groups share one conversation, so opening a group also exposes direct-message history to its members.

In the Web Shell channel editor, Who can talk in groups and Allowed group member IDs edit groups["*"], and Session operators edits operators. When senders is unset, the editor shows its effective default and writes nothing until you pick a value. Per-group overrides and an explicitly empty "operators": [] are set in settings.json; saving from the editor keeps them.

Group History Backfill Copy Section

By default, Qwen ignores unmentioned group messages and does not store them as session turns. To let the next @mention include recent group context, set groupHistoryLimit to a positive number.

{
  "channels": {
    "my-dingtalk": {
      "type": "dingtalk",
      "clientId": "$DINGTALK_CLIENT_ID",
      "clientSecret": "$DINGTALK_CLIENT_SECRET",
      "groupPolicy": "open",
      "groupHistoryLimit": 50,
      "groups": {
        "*": { "requireMention": true },
        "sensitive-group-id": {
          "requireMention": true,
          "groupHistoryLimit": 0
        }
      }
    }
  }
}

• Omitted or 0 disables backfill.
• Group-level groupHistoryLimit overrides the channel-level value.
• Only messages from senders the group's senders setting admits are persisted (all admitted group members by default) — so senders: "open" also widens whose messages groupHistoryLimit records.
• Messages rejected by groupPolicy or group allowlist are not persisted.
• Pending group history is stored as local JSONL under ~/.qwen/channels/<channel-name>-group-history.jsonl or $QWEN_HOME/channels/<channel-name>-group-history.jsonl.
• Cached messages are injected as untrusted context on the next real trigger and are not written as standalone session turns.

How group messages are evaluated Copy Section

1. groupPolicy — is this group disabled, listed, paired, or open? (no → ignore/pairing flow)
2. requireMention — was the bot mentioned/replied to? (no → no task; eligible history may be cached)
3. senders — is this member allowed?                  (open, or group member allowlist)
4. Route to session

Telegram Setup for Groups Copy Section

1. Add the bot to a group
2. Disable privacy mode in BotFather (/mybots → Bot Settings → Group Privacy → Turn Off) — otherwise the bot won't see non-command messages
3. Remove and re-add the bot to the group after changing privacy mode (Telegram caches this setting)

Finding a Group Chat ID Copy Section

To find a group's chat ID for the groups allowlist:

1. Stop the bot if it's running
2. Send a message mentioning the bot in the group
3. Use the Telegram Bot API to check queued updates:

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" | python3 -m json.tool

Look for message.chat.id in the response — group IDs are negative numbers (e.g., -5170296765).

Media Support Copy Chapter

Channels support sending images and files to the agent, not just text.

Images Copy Section

Send a photo to the bot and the agent will see it — useful for sharing screenshots, error messages, or diagrams. The image is sent directly to the model as a vision input.

To use image support, configure a multimodal model for the channel:

{
  "channels": {
    "my-channel": {
      "type": "telegram",
      "model": "qwen3.5-plus",
      ...
    }
  }
}

Files Copy Section

Send a document (PDF, code file, text file, etc.) to the bot. The file is downloaded and saved to a temporary directory, and the agent is told the file path so it can read the contents using its file-reading tools.

Files work with any model — no multimodal support required.

Platform differences Copy Section

QQ Bot accepts images, videos, files, and voice messages. An image is passed to the agent as vision input and is also saved to a temporary local path; a video or a file is saved to a temporary local path and the agent is told that path, with a file keeping the sender's extension so the read tool can classify it. A voice message is saved as audio — the platform's SILK-to-WAV conversion is preferred when available — and needs no text to start a turn. Image input requires a model that accepts images — with a text-only model the agent still gets the path. See QQ Bot for details.

WeCom accepts text, images, mixed text plus images, files, videos, and voice messages (transcribed). Images are passed to the agent as attachments; files and videos are downloaded to temporary local paths. See WeCom for details.

Dispatch Modes Copy Chapter

Controls what happens when you send a new message while the bot is still processing a previous one.

• steer (default) — The bot cancels the current request and starts working on your new message. Best for normal chat, where a follow-up usually means you want to correct or redirect the bot.
• collect — Your new messages are buffered. When the current request finishes, all buffered messages are combined into a single follow-up prompt. Good for async workflows where you want to queue up thoughts.
• followup — Each message is queued and processed as its own separate turn, in order. Useful for batch workflows where each message is independent.

{
  "channels": {
    "my-channel": {
      "type": "telegram",
      "dispatchMode": "steer",
      ...
    }
  }
}

You can also set dispatch mode per group, overriding the channel default:

{
  "groups": {
    "*": { "requireMention": true, "dispatchMode": "steer" },
    "-100123456": { "dispatchMode": "collect" }
  }
}

Response delivery Copy Chapter

Channels use their normal response delivery path. The shared delivery layer sends completed responses, and adapters may provide native progressive display, such as updating an interactive card in place. Platform message-length limits may still split long responses.

The obsolete blockStreaming, blockStreamingChunk, and blockStreamingCoalesce settings are no longer supported and can be removed from channel configuration. They do not affect delivery. Channel settings management rejects newly added or changed values for these fields. An unchanged stored value is retained, or removed, when the edit keeps the channel's type; changing a channel's type requires removing these fields first.

Turn output mode Copy Section

outputMode is a shared channel setting with adapter opt-in. Currently only DingTalk supports it and defaults to per_turn when the setting is omitted. Other adapters retain their existing behavior and receive no output-mode default: the channel editor does not offer this field, and configuration parsing or management saves reject an explicit value on unsupported adapters.

• per_task waits for the main task and its associated background tasks and notifications, then delivers one final result containing the last non-empty assistant reply for that task.
• per_response delivers each complete assistant response, not each token chunk.
• per_turn delivers the last non-empty assistant reply within each turn. The main turn finishes immediately when its prompt ends; later background notification turns deliver separate results.

In the default per_turn mode, a later background callback cannot reopen or replace the completed main result. A main result followed by eleven independent callback turns can therefore produce twelve result messages or cards. Choose per_task when the final result should wait for the associated background work. These modes select assistant output; they do not generate an extra summary or concatenate every intermediate reply.

The selected policy applies whether interactive cards are enabled or replies use ordinary messages. The shared layer owns output selection and task/turn coordination; native rendering, media and fallback delivery remain adapter-specific. See DingTalk turn output mode for presentation details and the conversation scope. Channel loops and webhook runs are unchanged.

Scheduled Channel Loops Copy Chapter

Channels have a persistent scheduler for prompts that should run later and push
their result back to the same chat. You can ask the agent naturally, for
example, Every 15 minutes, check the deployment and report any change, or use
the local commands directly:

/loop add "*/15 * * * *" check the deployment and report any change
/loop list
/loop inspect <id>
/loop cancel <id>

The agent uses the channel_loop_create, channel_loop_list, and
channel_loop_cancel tools when it manages these jobs for you. Schedules use
standard five-field cron expressions in the machine's local time. The job runs
unattended and its final response is delivered automatically to the chat that
created it.

Channel loops differ from the session-scoped tasks described in
Run Prompts on a Schedule:

• They are stored under $QWEN_HOME/channels/ — standalone channels use
  cron.json directly, while daemon-managed channels use a per-workspace file
  under daemon/. Both survive channel restarts.
• They are scoped to the current channel chat or thread. Each target can have up
  to 10 enabled loops, and each prompt is limited to 4,000 characters.
• They require an adapter and target that support proactive delivery. Telegram,
  DingTalk, Feishu, and WeCom opt in, subject to platform-specific target
  restrictions.
• They are unavailable with sessionScope: "single" because that scope is not
  tied to one chat target.
• A saved loop is disabled if its target is no longer authorized when it is due.

Background Agent Results Copy Chapter

When the agent delegates work to a background subagent or fork, the completion
result is delivered back to the channel chat that owns the session. Delivery
can happen after the original turn has ended, so keep the channel service or
daemon running while background work is active.

Slash Commands Copy Chapter

Channels support slash commands. These are handled locally (no agent round-trip):

• /help — List available commands
• /clear — Clear your session and start fresh (aliases: /reset, /new)
• /status — Show session info and access policy
• /btw <question> — Ask a side question without interrupting the current task; text-only questions up to 4096 characters, requires an agent connection with side-question support
• /sessions [all] — List open named tasks, or include closed tasks; available only with multiSession: true
• /session current — Show the selected named task
• /session new <name> — Create and select a shared-workspace task
• /session new <name> --worktree — Create and select a task in its own Git worktree; daemon-managed named-task mode only
• /session use <name> — Select an open task or reopen a closed task
• /session cancel [<name>] — Cancel the selected task's active prompt, or name another owned task; independently queued turns are not cancelled, but collect-mode follow-ups buffered behind the cancelled prompt are discarded by the existing cancellation behavior; media preparation is not targeted
• /session close <name> — Close a task without deleting its transcript
• /loop add "<cron>" — Create a persistent scheduled channel loop
• /loop list — List loops for the current chat
• /loop inspect — Show loop status and run details
• /loop cancel — Disable a loop

All other slash commands (e.g., /compress, /summary) are forwarded to the agent. Named-task commands are registered only when the mode is enabled, so /sessions remains agent-visible for existing configurations.

Named-task commands work on all channel types (Telegram, WeChat, QQ, DingTalk, WeCom, Feishu, GitHub). /cancel is currently registered only by Telegram, and loop creation requires proactive delivery support for the current adapter and target.

Running Copy Chapter

# Start all configured channels (shared agent process)
qwen channel start

# Start a single channel
qwen channel start my-channel

# Check if the service is running
qwen channel status

# Stop the running service
qwen channel stop

The bot runs in the foreground. Press Ctrl+C to stop, or use qwen channel stop from another terminal.

Experimental Daemon-Managed Mode Copy Section

You can also run configured channels under qwen serve:

# Start one channel under the daemon lifecycle
qwen serve --channel my-channel

# Start all configured channels
qwen serve --channel all

# Or enable channels later on a token-protected daemon
QWEN_SERVER_TOKEN=secret qwen serve
qwen channel set my-channel --token secret

# Query or stop the daemon-managed selection
qwen channel status --daemon-url http://127.0.0.1:4170 --token secret
qwen channel stop --daemon-url http://127.0.0.1:4170 --token secret

This mode starts workspace-grouped channel worker processes owned by qwen serve. Workers connect back to the daemon through the SDK and use the same channel adapters. They are separate from the daemon process, so a channel adapter crash does not crash the daemon. An explicit --channel selection takes precedence and fails daemon startup if it cannot become ready. On a flagless boot, every trusted registered workspace's own serve.channels setting is restored, and a name that cannot be hosted is skipped with a log instead of stopping the others. all remains primary-workspace only. Registering a workspace later restores its channels too — without holding the registration open — once per daemon run, and not at all when the daemon was started with an explicit --channel or after qwen channel stop. Unlike the boot restore, one name it cannot host costs that workspace its whole list. Without any of these sources, the daemon does not load channel adapters or reserve the lease until the first qwen channel set, or until a workspace that configures its own serve.channels registers.

Automatic restore skips invalid startup settings and validation or lease failures that occur before workers start, while preserving unrelated settings. After a worker startup fails, the daemon continues only once cleanup succeeds. A global runtime startup timeout or an unconfirmed worker stop still follows the normal startup-failure path; the service lease remains held while worker termination is unconfirmed. Check the daemon log for messages identifying serve.channels when a channel does not restore.

Stored startup names must be non-empty, have no leading or trailing whitespace, and contain no unsafe control or invisible characters. Invalid entries are skipped individually and logged by their array index. Startup does not rename instances or rewrite the configuration. The channel startup toggle reflects the saved setting; runtime state shows whether the channel is running.

qwen serve --channel is not the same service as qwen channel start. Standalone qwen channel start still uses the ACP-backed channel service and can run channel configs with different cwd values. Daemon-managed channels require every selected channel's cwd to resolve to a workspace registered by the daemon. In multi-workspace mode, a selection replacement keeps workers for workspaces whose ordered channel list did not change; all remains primary-workspace-only.

Without --daemon-url, qwen channel status and qwen channel stop retain standalone pidfile behavior. Their --daemon-url variants query or stop the daemon manager. Runtime selections are not written to settings and do not survive daemon restart. If a ready worker exits unexpectedly, the daemon continues running and reports a channel-worker warning in /daemon/status.

Webhook-triggered tasks Copy Chapter

Daemon-managed channels can also accept authenticated webhook events. Qwen receives the event as context, summarizes and decides what matters, and then delivers the final response to the configured chat target. This is not a raw notification relay.
Webhook tasks require approvalMode: "yolo" because they run without interactive approval. That setting applies to the whole channel, not only webhook turns, so use a dedicated webhook channel or tightly restrict normal chat senders for that channel.

Example channel config:

{
  "channels": {
    "dingtalk-main": {
      "type": "dingtalk",
      "clientId": "$DINGTALK_CLIENT_ID",
      "clientSecret": "$DINGTALK_CLIENT_SECRET",
      "cwd": "/repo",
      "privatePolicy": "allowlist",
      "allowedUsers": ["12345"],
      "approvalMode": "yolo",
      "sessionScope": "user",
      "webhooks": {
        "sources": {
          "github-ci": {
            "secretEnv": "QWEN_CHANNEL_GITHUB_CI_SECRET",
            "targets": {
              "operator": {
                "chatId": "DINGTALK_USER_ID",
                "senderId": "webhook:github-ci",
                "isGroup": false
              },
              "team": {
                "chatId": "OPEN_CONVERSATION_ID",
                "senderId": "webhook:github-ci",
                "isGroup": true
              }
            }
          }
        }
      }
    }
  }
}

For DingTalk, set isGroup explicitly on every target. A direct-message target uses the DingTalk user ID as chatId with isGroup: false; a group target uses the group openConversationId with isGroup: true. Other adapters may require their own proactive target shape.

Daemon-managed DingTalk, Feishu, Telegram, and WeCom channels dynamically observe contacts from authorized inbound messages. List contacts observed in the primary workspace during the default seven-day freshness window:

curl -H "Authorization: Bearer $QWEN_SERVER_TOKEN" \
  http://127.0.0.1:4170/workspace/channel/observed-contacts

Use GET /workspaces/:workspace/channel/observed-contacts to select another registered, trusted workspace. Add ?freshWithinSeconds=N to choose a window from one second through 365 days. The daemon advertises this API with the workspace_channel_observed_contacts capability.

The response returns complete platform IDs and labels. Group labels use names already present in accepted inbound messages when available: DingTalk supplies conversationTitle, and Telegram supplies chat.title. Feishu and WeCom group labels currently fall back to their complete IDs; no platform directory or group-detail API is queried. Topic labels also fall back to complete IDs. Each lastObservedAt is a canonical ISO 8601 UTC timestamp with millisecond precision; clients can convert it to the user's local time zone for display. Top-level users contains users observed in direct messages. groups contains observed group conversations, groups[].users contains users observed in each group, and groups[].topics[].users contains users observed in Feishu or Telegram topics:

{
  "users": [
    {
      "channelName": "feishu-main",
      "label": "Example User",
      "id": "ou_complete_user_id",
      "lastObservedAt": "2026-07-17T08:00:00.000Z"
    }
  ],
  "groups": [
    {
      "channelName": "feishu-main",
      "label": "oc_complete_chat_id",
      "id": "oc_complete_chat_id",
      "lastObservedAt": "2026-07-17T08:05:00.000Z",
      "users": [
        {
          "label": "Example User",
          "id": "ou_complete_user_id",
          "lastObservedAt": "2026-07-17T08:05:00.000Z"
        }
      ],
      "topics": []
    }
  ]
}

These nested users are observed participants, not authoritative group membership. Only messages that pass direct/group, mention, sender, and pairing gates are recorded. Repeated observations refresh labels and timestamps; passive observation cannot detect a leave or deletion until the relationship becomes stale. Message content is never stored. The bounded registry lives under $QWEN_HOME/channels/daemon/<workspaceHash>/observed-contacts.json, outside the workspace checkout and partitioned per workspace. Its 500-observation limit is shared by all channels and conversations in that workspace, and observations older than 365 days are removed on the next accepted write. If the registry becomes malformed or uses an unsupported version, delete that file to reset it; accepted traffic recreates it. Webhook configuration and delivery are unchanged.

Start qwen serve with the channel worker enabled:

QWEN_SERVER_TOKEN="$QWEN_SERVER_TOKEN" qwen serve --require-auth --channel dingtalk-main

Example request:

curl -X POST "http://127.0.0.1:4170/channels/dingtalk-main/webhooks/github-ci" \
  -H "x-qwen-webhook-secret: $QWEN_CHANNEL_GITHUB_CI_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "push",
    "targetRef": "operator",
    "title": "CI pipeline finished",
    "payload": {
      "targetRef": "refs/heads/main",
      "repository": "qwen-code",
      "status": "success"
    }
  }'

Webhook routes authenticate with the webhook secret header, even when qwen serve is running with bearer auth enabled. Do not share the daemon bearer token with webhook providers. Webhook config and secretEnv values are loaded when the daemon starts; restart qwen serve after changing webhook sources or rotating secrets. A 202 {"accepted": true} response means the channel worker accepted ownership of the task, not that the final response has already been delivered to chat. Check daemon and channel worker logs, plus /daemon/status, when troubleshooting delivery failures.

Multi-Channel Mode Copy Section

When you run qwen channel start without a name, all channels defined in settings.json start together sharing a single agent process. Each channel maintains its own sessions — a Telegram user and a WeChat user get separate conversations, even though they share the same agent.

Each channel uses its own cwd from its config, so different channels can work on different projects simultaneously.

Service Management Copy Section

The channel service uses a PID file (~/.qwen/channels/service.pid) to track the running instance:

• Duplicate prevention: Running qwen channel start while a service is already running will show an error instead of starting a second instance
• qwen channel stop: Gracefully stops the running service from another terminal
• qwen channel status: Shows whether the service is running, its uptime, and session counts per channel

Crash Recovery Copy Section

If the agent process crashes unexpectedly, the channel service automatically restarts it and attempts to restore all active sessions. Users can continue their conversations without starting over.

• Sessions are persisted to ~/.qwen/channels/sessions.json while the service is running
• On crash: the agent restarts within 3 seconds and reloads saved sessions
• After 3 consecutive crashes, the service exits with an error
• On clean shutdown (Ctrl+C or qwen channel stop): session data is cleared — the next start is always fresh

Design Openrouter Auth And Models (`docs/design/openrouter-auth-and-models.md`) Copy Section

OpenRouter Auth and Model Management Design

This document captures the design intent behind the OpenRouter auth flow and the
model management changes introduced with it. It intentionally focuses on the
product and architectural choices, not implementation history.

Goals Copy Chapter

• Let users authenticate with OpenRouter from both CLI and /auth.
• Reuse the existing OpenAI-compatible provider path instead of adding a new auth
  type for OpenRouter.
• Make the first-run experience usable without asking users to manage hundreds of
  models immediately.
• Keep a clear path toward richer model management via /manage-models.

OpenRouter Auth Copy Chapter

OpenRouter is integrated as an OpenAI-compatible provider:

• auth type: AuthType.USE_OPENAI
• provider settings: modelProviders.openai
• API key env var: OPENROUTER_API_KEY
• base URL: https://openrouter.ai/api/v1

This avoids introducing an OpenRouter-specific AuthType when the runtime model
provider path is already OpenAI-compatible. It keeps auth status, model
resolution, provider selection, and settings schema aligned with the existing
provider abstraction.

The user-facing flows are:

• /auth → OpenRouter for the interactive TUI flow.
• Environment variables for automation or direct API-key setup:
  OPENROUTER_API_KEY plus OPENAI_BASE_URL=https://openrouter.ai/api/v1.
• ~/.qwen/settings.json for scripted setup that needs explicit model provider
  entries.

Browser OAuth uses OpenRouter's PKCE flow and writes the exchanged API key into
settings before refreshing auth as AuthType.USE_OPENAI.

Model Management Copy Chapter

OpenRouter exposes a large dynamic model catalog. Writing every discovered model
into modelProviders.openai would make /model noisy and would turn a long-term
settings field into a cache of a remote catalog.

The key design split is:

• Catalog: the full set of models discovered from a source such as
  OpenRouter.
• Enabled set: the smaller set of models that should appear in /model and
  be persisted in user settings.

For the initial OpenRouter flow, auth should finish with a useful default enabled
set instead of interrupting the user with a large picker. The recommended set
should be small, stable, and biased toward models that let users try the product
successfully, including free models when available.

/model remains a fast model switcher. It should not become the place where
users browse and curate a full provider catalog.

`/manage-models` Copy Chapter

Richer model management belongs in a separate /manage-models entry point. That
flow should let users:

• browse discovered models;
• search by id, display name, provider prefix, and derived tags such as free or
  vision;
• see which models are currently enabled;
• enable or disable models in batches.

The source dimension must remain part of this design. OpenRouter is only the
first dynamic catalog source; future sources such as ModelScope and ModelStudio
should fit the same shape. UI complexity can be reduced, but the underlying
source abstraction should stay available as the extension point.

Current Boundary Copy Chapter

This change should do the minimum needed to make OpenRouter auth and model setup
pleasant:

• OAuth or key-based auth configures OpenRouter through the existing
  OpenAI-compatible provider path.
• The initial enabled model set is curated instead of dumping the full catalog
  into settings.
• Full catalog storage, browsing, filtering, and batch management are deferred to
  /manage-models.

The design principle is simple: authentication should get users to a working
state quickly, while model curation should live in a dedicated management flow.

Developers Architecture (`docs/developers/architecture.md`) Copy Section

Qwen Code Architecture Overview

Qwen Code is a monorepo that supports an interactive terminal, headless and
programmatic execution, the Agent Client Protocol (ACP), a long-running HTTP
daemon, web and IDE clients, and messaging-channel adapters. This document maps
those surfaces to the packages that implement them and explains the main
runtime boundaries.

For detailed daemon internals, start with the
daemon documentation. For HTTP request and event
shapes, see the qwen serve protocol reference.

System at a glance Copy Chapter

Qwen Code has two agent execution models:

• Direct execution: the interactive TUI and headless CLI construct and run
  the agent runtime directly.
• ACP execution: qwen --acp hosts the agent behind an ACP transport. It
  can be driven by an ACP client directly or by qwen serve through the shared
  ACP bridge.

qwen serve adds an HTTP + Server-Sent Events (SSE) control plane around ACP
execution so multiple clients can use long-lived, workspace-scoped runtimes.

flowchart TB
    subgraph surfaces["User and integration surfaces"]
        TUI["Interactive TUI / headless CLI"]
        PQ["TypeScript SDK process client"]
        WEB["Web Shell / shared Web UI"]
        IDE["IDE integrations"]
        CHANNEL["Messaging channels"]
        CUSTOM["Custom daemon clients"]
    end

    subgraph hosts["Process and transport hosts"]
        CLI["CLI host<br/>packages/cli"]
        SDK["Daemon client<br/>packages/sdk-typescript"]
        SERVE["qwen serve<br/>packages/cli/src/serve"]
        BRIDGE["ACP bridge<br/>packages/acp-bridge"]
        ACP["qwen --acp child"]
    end

    subgraph runtime["Agent runtime"]
        CORE["Agent orchestration and tools<br/>packages/core"]
    end

    subgraph external["External systems"]
        MODEL["Model providers"]
        MCP["MCP servers"]
        HOST["Workspace filesystem and processes"]
    end

    TUI --> CLI
    PQ --> CLI
    CLI --> CORE

    WEB --> SDK
    IDE --> SDK
    CHANNEL --> SDK
    CUSTOM --> SDK
    SDK --> SERVE
    SERVE --> BRIDGE
    BRIDGE --> ACP
    ACP --> CORE

    CORE --> MODEL
    CORE --> MCP
    CORE --> HOST

The diagram shows the main production paths. Some adapters also have standalone
modes: for example, qwen channel start uses the ACP bridge without requiring
an HTTP daemon. See the
channel plugin guide for those variants.

Repository layout Copy Chapter

Most code lives in npm workspaces under packages/. A package should depend on
another package through its declared public exports rather than through a
relative path into that package's source tree.

Package boundaries Copy Chapter

CLI and presentation surfaces Copy Section

packages/cli owns the executable and chooses the runtime mode from command-line
arguments. It loads user and workspace settings, constructs the core
configuration, enters the requested sandbox when necessary, and then starts one
of the interactive, headless, ACP, daemon, channel, or maintenance flows.

Presentation remains outside the core runtime:

• the Ink TUI renders local interactive sessions;
• packages/web-shell adapts daemon state to React providers and hooks and
  provides the browser experience;
• IDE and channel packages translate host-specific events into shared client or
  bridge contracts.

Core runtime Copy Section

packages/core owns the agent loop. It constructs model requests, maintains
conversation context, dispatches tool calls, applies permission policy, and
returns structured events and results to the active host. Built-in tools cover
file operations, shell execution, search, planning, web access, memory, skills,
and subagents. MCP extends the tool and resource surface without coupling the
runtime to a specific integration.

The core package does not decide how results are displayed or how a remote
client transports them. Those decisions belong to the CLI, bridge, SDK, and UI
layers.

ACP bridge Copy Section

packages/acp-bridge connects a host process to an ACP agent runtime. Its main
responsibilities are:

• spawning or attaching to an ACP channel;
• multiplexing sessions and clients;
• forwarding prompts, cancellations, and ACP notifications;
• mediating permission requests;
• publishing bounded session event streams;
• providing a workspace filesystem interface to the host.

The bridge can use a real qwen --acp child process in production or an
in-memory channel in tests. See the
@qwen-code/acp-bridge README for its
public entry points.

SDK and UI adapters Copy Section

The TypeScript SDK exposes two client styles:

• query() starts and controls a Qwen Code process for programmatic local use;
• daemon clients communicate with qwen serve over HTTP and SSE.

packages/web-shell builds a React state layer and browser UI on the daemon
client. Other clients,
including IDE integrations and daemon-managed channels, reuse the same SDK and
event contracts instead of importing server implementation code.

Runtime flows Copy Chapter

Direct CLI flow Copy Section

1. The CLI parses arguments and resolves user, workspace, environment, and
   command-line configuration.
2. It prepares sandboxing and constructs the core runtime configuration.
3. The core runtime builds the model request and enters the agent/tool loop.
4. Tool calls are checked against permission policy and executed in the active
   workspace environment.
5. The CLI renders incremental events in the TUI or serializes them for
   headless output.

Daemon flow Copy Section

1. A client uses the TypeScript SDK or the documented HTTP API to connect to
   qwen serve.
2. The daemon authenticates the request and resolves the workspace that owns
   the requested operation.
3. The workspace runtime forwards agent operations through its ACP bridge to a
   qwen --acp child.
4. The child runs the same core agent and tool logic used by direct execution.
5. Responses and notifications return through the bridge; session events are
   delivered to clients over SSE.

With multi-workspace sessions enabled, each live workspace runtime owns its own
bridge and ACP child. Filesystem access, environment overlays, MCP transports,
sessions, and failure handling remain scoped to that resolved runtime. The
daemon architecture documents the process
topology, trust boundaries, event replay, and lifecycle in detail.

Extension points Copy Chapter

Qwen Code can be extended at several layers:

• MCP servers add tools, prompts, and resources to the core runtime.
• Extensions and skills package reusable commands, configuration, and agent
  behavior.
• Channel plugins adapt messaging platforms to the shared channel runtime.
• SDK clients build custom local or daemon-backed applications.
• UI adapters project shared daemon events into host-specific state and
  presentation.

Keep platform-specific concerns in adapters. Shared agent behavior belongs in
the core runtime, while transport and wire behavior belongs in the ACP bridge,
SDK, or daemon host.

Configuration and state Copy Chapter

The CLI assembles effective configuration from command-line arguments,
environment variables, user settings, workspace settings, and defaults before
constructing the runtime. The core receives the resolved configuration rather
than reading presentation-specific input. See
Settings for the supported settings and
their scopes.

Direct sessions persist their history and metadata through shared core
services. In daemon mode, the daemon resolves the owning workspace and exposes
workspace- and session-scoped operations to clients; the ACP child remains the
owner of live agent execution.

Where to go next Copy Chapter

• Daemon developer documentation
• qwen serve HTTP protocol
• TypeScript SDK
• ACP bridge
• Channel plugin developer guide
• Tool development
• Integration testing

Developers Channel Plugins (`docs/developers/channel-plugins.md`) Copy Section

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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.

The Envelope Copy Chapter

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

Attachments Copy Section

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 Copy Chapter

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 Copy Chapter

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.

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

Reference Implementations Copy Chapter

• 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

Developers Contributing (`docs/developers/contributing.md`) Copy Section

How to Contribute

We would love to accept your patches and contributions to this project.

Contribution Process Copy Chapter

Code Reviews Copy Section

All submissions, including submissions by project members, require review. We
use GitHub pull requests
for this purpose.

Pull Request Guidelines Copy Section

To help us review and merge your PRs quickly, please follow these guidelines. PRs that do not meet these standards may be closed.

1. Link to an Existing Issue

All PRs should be linked to an existing issue in our tracker. This ensures that every change has been discussed and is aligned with the project's goals before any code is written.

• For bug fixes: The PR should be linked to the bug report issue.
• For features: The PR should be linked to the feature request or proposal issue that has been approved by a maintainer.

If an issue for your change doesn't exist, please open one first and wait for feedback before you start coding.

2. Keep It Small and Focused

We favor small, atomic PRs that address a single issue or add a single, self-contained feature.

• Do: Create a PR that fixes one specific bug or adds one specific feature.
• Don't: Bundle multiple unrelated changes (e.g., a bug fix, a new feature, and a refactor) into a single PR.

As a rule of thumb, start splitting a PR once it exceeds about 1,200 changed
lines. PRs above about 2,000 changed lines should either be split into a series
of smaller, logical PRs that can be reviewed and merged independently, or
explain in the PR description why the change needs to land together.

3. Use Draft PRs for Work in Progress

If you'd like to get early feedback on your work, please use GitHub's Draft Pull Request feature. This signals to the maintainers that the PR is not yet ready for a formal review but is open for discussion and initial feedback.

4. Ensure All Checks Pass

Before submitting your PR, ensure that all automated checks are passing by running npm run preflight. This command runs all tests, linting, and other style checks.

5. Update Documentation

If your PR introduces a user-facing change (e.g., a new command, a modified flag, or a change in behavior), you must also update the relevant documentation in the /docs directory.

New or updated design documents must include complete English (<name>.md) and
Simplified Chinese (<name>.zh-CN.md) versions in the same directory and PR.
Keep their structure, decisions, constraints, and acceptance criteria aligned,
and add reciprocal language links. See the design documentation requirements
in English or 简体中文.

6. Write Clear Commit Messages and a Good PR Description

Your PR should have a clear, descriptive title and a detailed description of the changes. Follow the Conventional Commits standard for your commit messages.

• Good PR Title: feat(cli): Add --json flag to 'config get' command
• Bad PR Title: Made some changes

In the PR description, explain the "why" behind your changes and link to the relevant issue (e.g., Fixes #123).

Development Setup and Workflow Copy Chapter

This section guides contributors on how to build, modify, and understand the development setup of this project.

Setting Up the Development Environment Copy Section

Prerequisites:

1. Node.js:
   • Development: Please use Node.js >=22. Ink 7 (used by the TUI) requires Node 22, and react@^19.2.0 is the matching peer. You can use a tool like nvm to manage Node.js versions.
   • Production: For running the CLI in a production environment, any version of Node.js >=22 is acceptable.
2. Git

Build Process Copy Section

To clone the repository:

git clone https://github.com/QwenLM/qwen-code.git # Or your fork's URL
cd qwen-code

To install dependencies defined in package.json as well as root dependencies:

npm install

To build the entire project (all packages):

npm run build

This command typically compiles TypeScript to JavaScript, bundles assets, and prepares the packages for execution. Refer to scripts/build.js and package.json scripts for more details on what happens during the build.

Enabling Sandboxing Copy Section

Sandboxing is highly recommended and requires, at a minimum, setting QWEN_SANDBOX=true in your ~/.env and ensuring a sandboxing provider (e.g. macOS Seatbelt, docker, or podman) is available. See Sandboxing for details.

To build both the qwen CLI utility and the sandbox container, run build:all from the root directory:

npm run build:all

To skip building the sandbox container, you can use npm run build instead.

Running Copy Section

To start the Qwen Code application from the source code (after building), run the following command from the root directory:

npm start

If you'd like to run the source build outside of the qwen-code folder, you can utilize npm link path/to/qwen-code/packages/cli (see: docs) to run with qwen

Running Tests Copy Section

This project contains two types of tests: unit tests and integration tests.

Unit Tests

To execute the unit test suite for the project:

npm run test

This will run tests located in the packages/core and packages/cli directories. Ensure tests pass before submitting any changes. For a more comprehensive check, it is recommended to run npm run preflight.

Integration Tests

The integration tests are designed to validate the end-to-end functionality of Qwen Code. They are not run as part of the default npm run test command.

To run the integration tests, use the following command:

npm run test:e2e

For more detailed information on the integration testing framework, please see the Integration Tests documentation.

Linting and Preflight Checks Copy Section

To ensure code quality and formatting consistency, run the preflight check:

npm run preflight

This command will run ESLint, Prettier, all tests, and other checks as defined in the project's package.json.

ProTip

after cloning create a git precommit hook file to ensure your commits are always clean.

echo "
# Run npm build and check for errors
if ! npm run preflight; then
  echo "npm build failed. Commit aborted."
  exit 1
fi
" > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

Formatting

To separately format the code in this project by running the following command from the root directory:

npm run format

This command uses Prettier to format the code according to the project's style guidelines.

Linting

To separately lint the code in this project, run the following command from the root directory:

npm run lint

Coding Conventions Copy Section

• Please adhere to the coding style, patterns, and conventions used throughout the existing codebase.
• Imports: Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages.

Project Structure Copy Section

• packages/: Contains the individual sub-packages of the project.
  • cli/: The command-line interface.
  • core/: The core backend logic for Qwen Code.
• docs/: Contains all project documentation.
• scripts/: Utility scripts for building, testing, and development tasks.

For more detailed architecture, see docs/architecture.md.

Documentation Development Copy Chapter

This section describes how to develop and preview the documentation locally.

Prerequisites Copy Section

1. Ensure you have Node.js (version 22+) installed
2. Have npm or yarn available

Setup Documentation Site Locally Copy Section

To work on the documentation and preview changes locally:

1. Navigate to the docs-site directory:

   bash Copy

   cd docs-site

2. Install dependencies:

   bash Copy

   npm install

3. Link the documentation content from the main docs directory:

   bash Copy

   npm run link

   This creates a symbolic link from ../docs to content in the docs-site project, allowing the documentation content to be served by the Next.js site.

4. Start the development server:

   bash Copy

   npm run dev

5. Open http://localhost:3000 in your browser to see the documentation site with live updates as you make changes.

Any changes made to the documentation files in the main docs directory will be reflected immediately in the documentation site.

Debugging Copy Chapter

VS Code: Copy Section

0. Run the CLI to interactively debug in VS Code with F5
1. Start the CLI in debug mode from the root directory:
   bash Copy

   npm run debug

   This command runs node --inspect-brk dist/index.js within the packages/cli directory, pausing execution until a debugger attaches. You can then open chrome://inspect in your Chrome browser to connect to the debugger.
2. In VS Code, use the "Attach" launch configuration (found in .vscode/launch.json).

Alternatively, you can use the "Launch Program" configuration in VS Code if you prefer to launch the currently open file directly, but 'F5' is generally recommended.

To hit a breakpoint inside the sandbox container run:

DEBUG=1 qwen

Note: If you have DEBUG=true in a project's .env file, it won't affect qwen due to automatic exclusion. Use .qwen/.env files for qwen-specific debug settings.

React DevTools Copy Section

To debug the CLI's React-based UI, you can use React DevTools. Ink, the library used for the CLI's interface, is compatible with React DevTools version 4.x.

1. Start the Qwen Code application in development mode:

   bash Copy

   DEV=true npm start

2. Install and run React DevTools version 4.28.5 (or the latest compatible 4.x version):

   You can either install it globally:

   bash Copy

   npm install [email protected]
   react-devtools

   Or run it directly using npx:

   bash Copy

   npx [email protected]

   Your running CLI application should then connect to React DevTools.

Sandboxing Copy Chapter

TBD

Manual Publish Copy Chapter

We publish an artifact for each commit to our internal registry. But if you need to manually cut a local build, then run the following commands:

npm run clean
npm install
npm run auth
npm run prerelease:dev
npm publish --workspaces

Developers Roadmap (`docs/developers/roadmap.md`) Copy Section

Qwen Code RoadMap

Objective: Catch up with Claude Code's product functionality, continuously refine details, and enhance user experience.

For more details, please see the list below.

Features Copy Chapter

Completed Features

Features to Develop

Distinctive Features to Discuss

Developers Sdk Java (`docs/developers/sdk-java.md`) Copy Section

Qwen Code Java SDK

The Qwen Code Java SDK provides a recommended daemon transport for qwen serve and retains the experimental legacy stdio API for compatibility. Both APIs ship in the same com.alibaba:qwencode-sdk artifact.

Requirements Copy Chapter

• Java >= 11 for 0.1.0-alpha
• Maven >= 3.9.2 when building or publishing this SDK from source
• A compatible qwen serve for the daemon API, or qwen-code >= 0.5.0 for the legacy stdio API

Dependencies Copy Section

• Logging API: org.slf4j:slf4j-api (choose an SLF4J provider in your application)
• Utilities: org.apache.commons:commons-lang3
• JSON Processing: Fastjson2 for encoding and Jackson Core for strict decoding
• Testing: JUnit 5 (org.junit.jupiter:junit-jupiter)

Installation Copy Chapter

Add the following dependency to your Maven pom.xml:

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>qwencode-sdk</artifactId>
    <version>0.1.0-alpha</version>
</dependency>

Or if using Gradle, add to your build.gradle:

implementation 'com.alibaba:qwencode-sdk:0.1.0-alpha'

Building and Running Copy Chapter

Build Commands Copy Section

# Compile the project
mvn compile

# Run tests
mvn test

# Package the JAR
mvn package

# Install to local repository
mvn install

Real daemon E2E from source Copy Section

Run the real-daemon Java integration tests from the repository root after building both the workspaces and the root CLI bundle:

npm run build
npm run bundle
npx tsx scripts/run-java-daemon-sdk-e2e.ts

npm run build alone does not refresh dist/cli.js; the E2E harness launches that bundle and fails with an explicit prerequisite error when it is missing.

Recommended daemon API Copy Chapter

Start qwen serve, then create an independent thread-scoped session. promptText returns only after a matching turn_complete; incomplete streams fail with PromptOutcomeIndeterminateException rather than returning partial text as success.

For the lifecycle guarantees assumed by 0.1.0-alpha, use the qwen-code build released from the same source revision as the SDK. The daemon must contain the idempotent per-client detach ledger from #7386, the per-epoch terminal guarantee from #7400, and this release's acknowledged admission cancellation plus FIFO cancel-drain fence. The #7400 commit alone is not sufficient: a same-wire daemon can acknowledge cancel before agent dispatch without stopping the admitted prompt, or let an unacknowledged session-scoped cancel reach a queued successor. The bundled ACP child uses one acknowledged admission-aware cancellation handshake; a custom standards-compliant ACP child without that extension receives one standard session/cancel notification. Feature negotiation cannot distinguish older same-wire daemon builds, so the SDK fails closed rather than reporting partial output as success.

The bundled cancellation handshake deliberately waits for the targeted prompt call to settle before the daemon dispatches its queued successor. It has no timeout that merely acknowledges cancellation: doing so could let a late session-scoped cancel reach the next prompt. If a provider, tool, or custom integration ignores its AbortSignal indefinitely, the cancel mutation can therefore remain outcome-unknown and that session must not be reused. Treat a formal prompt terminal received within the caller's observation boundary as authoritative; otherwise close or destroy the session after observation fails. Recovering a wedged shared ACP child without disturbing its sibling sessions requires stronger runtime isolation and is outside this alpha contract.

import com.alibaba.qwen.code.daemon.DaemonClient;
import com.alibaba.qwen.code.daemon.DaemonSessionClient;
import com.alibaba.qwen.code.daemon.PromptTextResult;
import java.net.URI;

try (DaemonClient daemon = DaemonClient.builder()
        .baseUri(URI.create("http://127.0.0.1:4170"))
        .build();
     DaemonSessionClient session = daemon.createSession()) {
    PromptTextResult result = session.promptText("Explain this repository");
    System.out.println(result.getText());
}

Callers that need to allocate the session identity before creation can pass an RFC UUID v1-v5. The SDK checks session_id_override before the mutation and reports a different returned ID as SessionCreationOutcomeUnknownException:

CreateSessionRequest request = CreateSessionRequest.builder()
        .sessionId("550E8400-E29B-41D4-A716-446655440000")
        .build();

try (DaemonSessionClient session = daemon.createSession(request)) {
    System.out.println(session.getSession().getSessionId());
}

The daemon normalizes the ID to lowercase and creates a new thread session. This is not an idempotent attach; after an ambiguous create outcome, recover with the known ID rather than retrying creation.

If qwen serve requires authentication, add
.bearerToken(System.getenv("QWEN_SERVER_TOKEN")) to the DaemonClient
builder. The SDK sends the bearer on REST and SSE requests and never puts it in
the URL.

Use startPrompt with a PromptObserver when you need ordered text, thought, tool, usage, permission, and raw event callbacks. Its acceptanceFuture() and completionFuture() views separately expose daemon admission and the reliable turn terminal. respondToPermission() returns false when the request was already resolved or no longer pending. Cancelling the future views does not cancel the daemon prompt; use cancelActivePrompt() for the session-level daemon cancel operation and still wait for the matching terminal. A cooperative cancellation completes with turn_complete and stopReason=cancelled; promptText() returns its PromptTextResult, so callers that distinguish cancellation must inspect result.getTerminal().getStopReason(). If the agent or provider fails while cancelling, the daemon can instead publish turn_error, which makes promptText() throw PromptTurnException.

When cancellation, deadline, teardown, or agent settlement race, the daemon's exactly-once latch publishes the first formal terminal and suppresses later candidates. Always branch on the received terminal itself; the last control mutation sent by the client does not determine the terminal kind or error code.

The SSE transport sends Accept-Encoding: identity and Last-Event-ID, validates framing and event IDs, deduplicates replay, and reconnects only the SSE GET. Prompt and other mutation requests are never retried automatically. HTTP 408 and 5xx responses to prompt admission, session creation, permission, cancel, heartbeat, detach, or delete are reported as outcome-unknown because they do not prove that the daemon rejected the mutation. Finite response bodies and SSE observation have independent deadlines.

Creation-time model selection is intentionally not exposed by the Java daemon SDK API in this alpha. The daemon reports a rejected modelServiceId only as an SSE event emitted before the create response, while this SDK opens its stream from the later prompt-admission watermark. Until the daemon returns a definitive create result or the SDK owns a separate session-event subscription from Last-Event-ID: 0, use the daemon's configured default model.

PromptRequest.Builder.deadline(Duration) requests a daemon-enforced prompt deadline and is accepted only when the daemon advertises prompt_absolute_deadline; otherwise the SDK fails before sending the prompt. The value must be between 1 and 2,147,483,647 milliseconds, matching the daemon's Node timer range. This is separate from observationTimeout(Duration), which only bounds local SSE observation and never sends a cancel mutation.

Before creating a session, the SDK requires the daemon to advertise the REST transport and session_scope_override; this prevents an older daemon from silently ignoring the requested thread scope and attaching the client to a shared session. When a caller supplies a session ID, the SDK additionally requires session_id_override before sending the mutation. When client_heartbeat is advertised, an open session sends a fresh heartbeat every minute so the daemon does not reap an otherwise idle client. Set heartbeatInterval(Duration.ZERO) on the DaemonClient builder to disable this behavior, or choose a different positive interval. A heartbeat is never retried; the next scheduled heartbeat is a separate keepalive. Prompt observation is bounded to 32 concurrent prompts per client by default and can be adjusted with maximumConcurrentPrompts. Admission and terminal future callbacks run away from transport workers; callbacks that remain blocked consume bounded publication capacity. SSE stream cleanup is also bounded, and a close that remains blocked retains its cleanup reservation. Either condition can cause a later startPrompt to fail with DaemonClientCapacityException rather than dropping a timeout close or growing threads and queued work without limit.

An indeterminate completion is an outcome boundary, not a session-reuse boundary. After PromptAdmissionUnknownException or PromptOutcomeIndeterminateException, that DaemonSessionClient permanently rejects further prompts even if local stream cleanup later succeeds; close or destroy the session instead. An observation timeout is published without waiting forever for a blocked stream close, while cleanup continues asynchronously and retains bounded client capacity until it finishes.

Legacy stdio API Copy Chapter

The existing com.alibaba.qwen.code.cli API remains available:

public static void runSimpleExample() {
    List<String> result = QwenCodeCli.simpleQuery("hello world");
    result.forEach(logger::info);
}

For more advanced usage with custom transport options:

public static void runTransportOptionsExample() {
    TransportOptions options = new TransportOptions()
            .setModel("qwen3-coder-flash")
            .setPermissionMode(PermissionMode.AUTO_EDIT)
            .setCwd("./")
            .setEnv(new HashMap<String, String>() {{put("CUSTOM_VAR", "value");}})
            .setIncludePartialMessages(true)
            .setTurnTimeout(new Timeout(120L, TimeUnit.SECONDS))
            .setMessageTimeout(new Timeout(90L, TimeUnit.SECONDS))
            .setAllowedTools(Arrays.asList("read_file", "write_file", "glob"));

    List<String> result = QwenCodeCli.simpleQuery("who are you, what are your capabilities?", options);
    result.forEach(logger::info);
}

For streaming content handling with custom content consumers:

/* Detailed source-code truncated for AI context efficiency. */

other examples see src/test/java/com/alibaba/qwen/code/cli/example

Java 11 migration and alpha limits Copy Chapter

0.1.0-alpha raises the minimum Java version for the whole artifact from 8 to 11. Java 8 applications must remain on 0.0.3-alpha. Logback is no longer a runtime dependency; add the SLF4J provider your application uses.

This alpha deliberately fails closed when it cannot prove a prompt terminal. It does not guarantee exactly-once execution across daemon restarts, automatic epoch recovery, snapshot/resync, persisted cursors, or true prompt-ID-targeted cancellation. prompt_cancelled and queue events are advisory; only matching turn_complete and turn_error are terminal.

If session creation has an ambiguous transport outcome, the daemon may retain a session whose ID never reached the caller. The SDK does not retry creation and cannot detach that unknown session; daemon-side lifecycle reaping is the recovery boundary.

Architecture Copy Chapter

The artifact contains two isolated implementations:

• Daemon API: DaemonClient and DaemonSessionClient use REST mutations plus resumable SSE and own bounded HTTP, prompt, maintenance, and timer resources.
• Legacy stdio API: QwenCodeCli, Session, and ProcessTransport manage a child CLI process using the existing CLI protocol DTOs and utilities.

The daemon implementation does not reuse the legacy process transport, session model, DTOs, or global executor.

Legacy stdio features Copy Chapter

Permission Modes Copy Section

The SDK supports different permission modes for controlling tool execution:

• default: Write tools are denied unless approved via canUseTool callback or in allowedTools. Read-only tools execute without confirmation.
• plan: Blocks all write tools, instructing AI to present a plan first.
• auto-edit: Auto-approve edit tools (edit, write_file, notebook_edit) while other tools require confirmation.
• yolo: All tools execute automatically without confirmation.

Session Event Consumers and Assistant Content Consumers Copy Section

The SDK provides two key interfaces for handling events and content from the CLI:

SessionEventConsumers Interface

The SessionEventConsumers interface provides callbacks for different types of messages during a session:

• onSystemMessage: Handles system messages from the CLI (receives Session and SDKSystemMessage)
• onResultMessage: Handles result messages from the CLI (receives Session and SDKResultMessage)
• onAssistantMessage: Handles assistant messages (AI responses) (receives Session and SDKAssistantMessage)
• onPartialAssistantMessage: Handles partial assistant messages during streaming (receives Session and SDKPartialAssistantMessage)
• onUserMessage: Handles user messages (receives Session and SDKUserMessage)
• onOtherMessage: Handles other types of messages (receives Session and String message)
• onControlResponse: Handles control responses (receives Session and CLIControlResponse)
• onControlRequest: Handles control requests (receives Session and CLIControlRequest, returns CLIControlResponse)
• onPermissionRequest: Handles permission requests (receives Session and CLIControlRequest, returns Behavior)

AssistantContentConsumers Interface

The AssistantContentConsumers interface handles different types of content within assistant messages:

• onText: Handles text content (receives Session and TextAssistantContent)
• onThinking: Handles thinking content (receives Session and ThinkingAssistantContent)
• onToolUse: Handles tool use content (receives Session and ToolUseAssistantContent)
• onToolResult: Handles tool result content (receives Session and ToolResultAssistantContent)
• onOtherContent: Handles other content types (receives Session and AssistantContent)
• onUsage: Handles usage information (receives Session and AssistantUsage)
• onPermissionRequest: Handles permission requests (receives Session and CLIControlPermissionRequest, returns Behavior)
• onOtherControlRequest: Handles other control requests (receives Session and ControlRequestPayload, returns ControlResponsePayload)

Relationship Between the Interfaces

Important Note on Event Hierarchy:

• SessionEventConsumers is the high-level event processor that handles different message types (system, assistant, user, etc.)
• AssistantContentConsumers is the low-level content processor that handles different types of content within assistant messages (text, tools, thinking, etc.)

Processor Relationship:

• SessionEventConsumers → AssistantContentConsumers (SessionEventConsumers uses AssistantContentConsumers to process content within assistant messages)

Event Derivation Relationships:

• onAssistantMessage → onText, onThinking, onToolUse, onToolResult, onOtherContent, onUsage
• onPartialAssistantMessage → onText, onThinking, onToolUse, onToolResult, onOtherContent
• onControlRequest → onPermissionRequest, onOtherControlRequest

Event Timeout Relationships:

Each event handler method has a corresponding timeout method that allows customizing the timeout behavior for that specific event:

• onSystemMessage ↔ onSystemMessageTimeout
• onResultMessage ↔ onResultMessageTimeout
• onAssistantMessage ↔ onAssistantMessageTimeout
• onPartialAssistantMessage ↔ onPartialAssistantMessageTimeout
• onUserMessage ↔ onUserMessageTimeout
• onOtherMessage ↔ onOtherMessageTimeout
• onControlResponse ↔ onControlResponseTimeout
• onControlRequest ↔ onControlRequestTimeout

For AssistantContentConsumers timeout methods:

• onText ↔ onTextTimeout
• onThinking ↔ onThinkingTimeout
• onToolUse ↔ onToolUseTimeout
• onToolResult ↔ onToolResultTimeout
• onOtherContent ↔ onOtherContentTimeout
• onPermissionRequest ↔ onPermissionRequestTimeout
• onOtherControlRequest ↔ onOtherControlRequestTimeout

Default Timeout Values:

• SessionEventSimpleConsumers default timeout: 180 seconds (Timeout.TIMEOUT_180_SECONDS)
• AssistantContentSimpleConsumers default timeout: 60 seconds (Timeout.TIMEOUT_60_SECONDS)

Timeout Hierarchy Requirements:

For proper operation, the following timeout relationships should be maintained:

• onAssistantMessageTimeout return value should be greater than onTextTimeout, onThinkingTimeout, onToolUseTimeout, onToolResultTimeout, and onOtherContentTimeout return values
• onControlRequestTimeout return value should be greater than onPermissionRequestTimeout and onOtherControlRequestTimeout return values

Transport Options Copy Section

The TransportOptions class allows configuration of how the SDK communicates with the Qwen Code CLI:

• pathToQwenExecutable: Path to the Qwen Code CLI executable
• cwd: Working directory for the CLI process
• model: AI model to use for the session
• permissionMode: Permission mode that controls tool execution
• env: Environment variables to pass to the CLI process
• maxSessionTurns: Limits the number of conversation turns in a session
• coreTools: A non-empty allowlist of core tools. An omitted or empty list is treated as unspecified; an empty list does not disable tools. MCP and other non-core tools have separate registration and permission rules. Use excludeTools to exclude named tools explicitly; allowedTools controls approval rather than registration.
• excludeTools: List of tools to exclude from being available to the AI
• allowedTools: List of tools that are pre-approved for use without additional confirmation
• authType: Authentication type to use for the session
• includePartialMessages: Enables receiving partial messages during streaming responses
• turnTimeout: Timeout for a complete turn of conversation
• messageTimeout: Timeout for individual messages within a turn
• resumeSessionId: ID of a previous session to resume
• otherOptions: Additional command-line options to pass to the CLI

Session Control Features Copy Section

• Session creation: Use QwenCodeCli.newSession() to create a new session with custom options
• Session management: The Session class provides methods to send prompts, handle responses, and manage session state
• Session cleanup: Always close sessions using session.close() to properly terminate the CLI process
• Session resumption: Use setResumeSessionId() in TransportOptions to resume a previous session
• Session interruption: Use session.interrupt() to interrupt a currently running prompt
• Dynamic model switching: Use session.setModel() to change the model during a session
• Dynamic permission mode switching: Use session.setPermissionMode() to change the permission mode during a session

Thread Pool Configuration Copy Section

The SDK uses a thread pool for managing concurrent operations with the following default configuration:

• Core Pool Size: 30 threads
• Maximum Pool Size: 100 threads
• Keep-Alive Time: 60 seconds
• Queue Capacity: 300 tasks (using LinkedBlockingQueue)
• Thread Naming: "qwen_code_cli-pool-{number}"
• Daemon Threads: true
• Rejected Execution Handler: CallerRunsPolicy

Tasks still running or queued in the default pool are abandoned when the JVM exits. Callers that require completion must wait for those tasks explicitly.

Error Handling Copy Chapter

The SDK provides specific exception types for different error scenarios:

• SessionControlException: Thrown when there's an issue with session control, including attempting to use a closed or unavailable session. Session construction and start() can throw it directly; QwenCodeCli.newSession() wraps lower-level creation and initialization failures in a RuntimeException.
• SessionSendPromptException: Thrown when there's an issue sending a prompt or receiving a response

FAQ / Troubleshooting Copy Chapter

Q: Do I need to install the Qwen CLI separately? Copy Section

A: Yes. The daemon API requires a compatible qwen serve; the legacy stdio
API requires qwen-code 0.5.0 or higher.

Q: What Java versions are supported? Copy Section

A: 0.1.0-alpha requires Java 11 or higher. Java 8 users must remain on 0.0.3-alpha.

Q: How do I handle long-running requests? Copy Section

A: The SDK includes timeout utilities. You can configure timeouts using the Timeout class in TransportOptions.

Q: Why are some tools not executing? Copy Section

A: This is likely due to permission modes. Check your permission mode settings and consider using allowedTools to pre-approve certain tools.

Q: How do I resume a previous session? Copy Section

A: Use the setResumeSessionId() method in TransportOptions to resume a previous session.

Q: Can I customize the environment for the CLI process? Copy Section

A: Yes, use the setEnv() method in TransportOptions to pass environment variables to the CLI process.

License Copy Chapter

Apache-2.0 - see LICENSE for details.

Developers Sdk Python (`docs/developers/sdk-python.md`) Copy Section

Python SDK

`qwen-code-sdk` Copy Chapter

qwen-code-sdk is an experimental Python SDK for Qwen Code. v1 targets the
existing stream-json CLI protocol and keeps the transport surface small and
testable.

Scope Copy Chapter

• Package name: qwen-code-sdk
• Import path: qwen_code_sdk
• Runtime requirement: Python >=3.10
• CLI dependency: external qwen executable is required in v1
• Transport scope: process transport only
• Not included in v1: ACP transport, SDK-embedded MCP servers

Install Copy Chapter

pip install qwen-code-sdk

For preview releases:

pip install --pre qwen-code-sdk

If qwen is not on PATH, pass path_to_qwen_executable explicitly.
On Windows, the SDK discovers npm's qwen.cmd shim only through the effective
child PATH, ignoring extensionless shell shims and non-launchable PATHEXT
associations. A command in the current directory is considered only when that
directory is explicitly included in PATH.
You can override the lookup path through the env option; Windows environment
variable names are case-insensitive, so PATH, Path, and path are equivalent.
Closing a running Windows shim stops its CLI process tree through the system
taskkill utility; process exit and stderr cleanup waits have bounded timeouts.

Before writing SDK code, make sure the CLI works in the same shell:

qwen --version

Quick Start Copy Chapter

import asyncio

from qwen_code_sdk import (
    is_sdk_assistant_message,
    is_sdk_result_message,
    query,
)


def extract_text(message):
    content = message.get("message", {}).get("content", [])
    if not isinstance(content, list):
        return repr(content)
    texts = [
        block.get("text", "")
        for block in content
        if isinstance(block, dict) and block.get("type") == "text"
    ]
    return "".join(texts) if texts else "[no text content]"


def print_result(message):
    if message.get("is_error"):
        error = message.get("error") or {}
        print(f"Error: {error.get('message', 'Unknown error')}")
        return
    print(message.get("result", ""))


async def main() -> None:
    async with query(
        "Explain the repository structure.",
        {
            "cwd": "/path/to/project",
            "path_to_qwen_executable": "qwen",
        },
    ) as result:
        async for message in result:
            if is_sdk_assistant_message(message):
                print(extract_text(message))
            elif is_sdk_result_message(message):
                print_result(message)


asyncio.run(main())

asyncio.run() is appropriate for standalone scripts. If your application
already runs an event loop, such as Jupyter, FastAPI, or pytest-asyncio, call
await main() instead.

Sync Usage Copy Chapter

Use query_sync when your host application is not async:

from qwen_code_sdk import is_sdk_result_message, query_sync


with query_sync(
    "Summarize this repository in one paragraph.",
    {
        "cwd": "/path/to/project",
        "path_to_qwen_executable": "qwen",
    },
) as result:
    for message in result:
        if is_sdk_result_message(message):
            if message.get("is_error"):
                error = message.get("error") or {}
                print(f"Error: {error.get('message', 'Unknown error')}")
            else:
                print(message.get("result", ""))

API Surface Copy Chapter

Top-level entry points Copy Section

• query(prompt, options=None) -> Query
• query_sync(prompt, options=None) -> SyncQuery

prompt supports either:

• str for single-turn requests
• AsyncIterable[SDKUserMessage] for multi-turn streams

`Query` Copy Section

• Async iterable over SDK messages
• close()
• interrupt()
• set_model(model)
• set_permission_mode(mode)
• supported_commands()
• mcp_server_status()
• get_session_id()
• is_closed()

`QueryOptions` Copy Section

Use only one of resume, continue_session, or session_id in a request. The
SDK raises ValidationError if these session options are combined.

Unsupported in v1:

• mcp_servers

Common Configuration Copy Section

options = {
    "cwd": "/path/to/project",
    "path_to_qwen_executable": "qwen",
    "model": "qwen-plus",
    "permission_mode": "plan",
    "max_session_turns": 1,
    "env": {
        "OPENAI_MODEL": "qwen-plus",
    },
    "timeout": {
        "control_request": 60,
        "can_use_tool": 60,
        "stream_close": 60,
    },
}

Timeout values are seconds. env is merged on top of the parent process
environment, so you only need to pass variables that should differ for this SDK
session. Set secrets such as OPENAI_API_KEY in the parent environment or a
secrets manager rather than hardcoding them in source.

Permission Handling Copy Chapter

When the CLI emits a can_use_tool control request, the SDK routes it through
can_use_tool(tool_name, tool_input, context).

• Default behavior: deny
• Default timeout: 60 seconds, configurable with timeout.can_use_tool
• Timeout fallback: deny
• Callback exceptions: converted to deny with an error message
• Callback context: cancel_event, suggestions, and blocked_path
• Callback contract: can_use_tool must be async with 3 positional arguments;
  stderr must accept 1 positional string argument

Example:

/* Detailed source-code truncated for AI context efficiency. */

If you do not pass can_use_tool, the SDK denies permission requests by
default.

Multi-Turn Sessions Copy Chapter

For multi-turn sessions, pass an async iterable of SDKUserMessage objects:

import asyncio

from qwen_code_sdk import SDKUserMessage, is_sdk_result_message, query

SESSION_ID = "123e4567-e89b-12d3-a456-426614174000"


async def prompts():
    first: SDKUserMessage = {
        "type": "user",
        "session_id": SESSION_ID,
        "message": {
            "role": "user",
            "content": "Create a concise project summary.",
        },
        "parent_tool_use_id": None,
    }
    yield first

    second: SDKUserMessage = {
        "type": "user",
        "session_id": SESSION_ID,
        "message": {
            "role": "user",
            "content": "Also list the test files.",
        },
        "parent_tool_use_id": None,
    }
    yield second


async def main():
    async with query(
        prompts(),
        {
            "cwd": "/path/to/project",
            "path_to_qwen_executable": "qwen",
            "session_id": SESSION_ID,
        },
    ) as result:
        async for message in result:
            if is_sdk_result_message(message):
                if message.get("is_error"):
                    error = message.get("error") or {}
                    print(f"Error: {error.get('message', 'Unknown error')}")
                else:
                    print(message.get("result", ""))


asyncio.run(main())

All messages in the async iterable must be known upfront. The SDK sends them
sequentially to the CLI but cannot feed a prior response back into the generator.
If you need conversational turn-taking, manage each turn as a separate query()
call.

Runtime Controls Copy Chapter

The returned Query object can control the running CLI process:

import asyncio

from qwen_code_sdk import is_sdk_result_message, query


async def main():
    async with query(
        "Inspect this repository and explain the test layout.",
        {
            "cwd": "/path/to/project",
            "path_to_qwen_executable": "qwen",
        },
    ) as result:
        commands = await result.supported_commands()
        print(commands)

        await result.set_permission_mode("plan")
        await result.set_model("qwen-plus")

        async for message in result:
            if is_sdk_result_message(message):
                if message.get("is_error"):
                    error = message.get("error") or {}
                    print(f"Error: {error.get('message', 'Unknown error')}")
                else:
                    print(message.get("result", ""))


asyncio.run(main())

Use interrupt() to cancel the current operation, close() to clean up the
underlying process, and get_session_id() to persist a session id for later.

Session Resume Copy Chapter

import asyncio

from qwen_code_sdk import is_sdk_result_message, query


async def main():
    # Resume a known session by its id.
    async with query(
        "Continue from this session.",
        {
            "path_to_qwen_executable": "qwen",
            "resume": "123e4567-e89b-12d3-a456-426614174000",
        },
    ) as known:
        async for message in known:
            if is_sdk_result_message(message):
                if message.get("is_error"):
                    error = message.get("error") or {}
                    print(f"Error: {error.get('message', 'Unknown error')}")
                else:
                    print(message.get("result", ""))


asyncio.run(main())

To continue the latest session instead:

import asyncio

from qwen_code_sdk import is_sdk_result_message, query


async def main():
    async with query(
        "Continue the latest session.",
        {
            "path_to_qwen_executable": "qwen",
            "continue_session": True,
        },
    ) as latest:
        async for message in latest:
            if is_sdk_result_message(message):
                if message.get("is_error"):
                    error = message.get("error") or {}
                    print(f"Error: {error.get('message', 'Unknown error')}")
                else:
                    print(message.get("result", ""))


asyncio.run(main())

resume is useful when your application stores session ids. continue_session
delegates the selection of the latest session to the CLI.

Error Model Copy Chapter

• ValidationError: invalid options, invalid UUIDs, unsupported combinations
• ControlRequestTimeoutError: initialize, interrupt, or other control request
  timed out
• ProcessExitError: CLI exited non-zero
• AbortError: control request or session was cancelled

from qwen_code_sdk import (
    ProcessExitError,
    ValidationError,
    is_sdk_result_message,
    query_sync,
)

try:
    with query_sync("Say hello", {"path_to_qwen_executable": "qwen"}) as result:
        for message in result:
            if is_sdk_result_message(message):
                if message.get("is_error"):
                    error = message.get("error") or {}
                    print(f"Error: {error.get('message', 'Unknown error')}")
                else:
                    print(message.get("result", ""))
except ValidationError as exc:
    print(f"Invalid SDK options: {exc}")
except ProcessExitError as exc:
    print(f"qwen exited with {exc.exit_code}: {exc}")

Troubleshooting Copy Chapter

If the SDK cannot start the CLI:

• Verify qwen --version works in the target environment
• Pass path_to_qwen_executable if your shell uses nvm, pyenv, or other
  non-standard PATH setup
• Use debug=True or stderr=print to surface CLI stderr while debugging

If session control calls time out:

• Check that the target qwen version supports --input-format stream-json
• Increase timeout.control_request
• Verify that no wrapper script is swallowing stdout/stderr

Repository Integration Copy Chapter

Repository-level helper commands:

• npm run test:sdk:python
• npm run lint:sdk:python
• npm run typecheck:sdk:python
• npm run smoke:sdk:python -- --qwen qwen

Real E2E Smoke Copy Chapter

For a real runtime check (actual qwen process + real model call), run from
the repository root. The npm helper uses python3, so ensure it resolves to a
Python >=3.10 interpreter:

npm run smoke:sdk:python -- --qwen qwen

This script runs:

• async single-turn query
• async control flow (supported_commands, permission mode updates)
• sync query_sync query

It prints JSON and returns non-zero on failure.

Developers Sdk Typescript (`docs/developers/sdk-typescript.md`) Copy Section

Typescript SDK

@qwen-code/sdk Copy Chapter

A minimum experimental TypeScript SDK for programmatic access to Qwen Code.

Feel free to submit a feature request/issue/PR.

Installation Copy Chapter

npm install @qwen-code/sdk

Requirements Copy Chapter

• Node.js >= 22.0.0
• Qwen Code >= 0.4.0 (stable). The SDK uses its bundled CLI by default; set pathToQwenExecutable only when you need to run a custom qwen binary or CLI bundle.

Quick Start Copy Chapter

import { query } from '@qwen-code/sdk';

// Single-turn query
const result = query({
  prompt: 'What files are in the current directory?',
  options: {
    cwd: '/path/to/project',
  },
});

// Iterate over messages
for await (const message of result) {
  if (message.type === 'assistant') {
    console.log('Assistant:', message.message.content);
  } else if (message.type === 'result') {
    console.log('Result:', message.result);
  }
}

API Reference Copy Chapter

`query(config)` Copy Section

Creates a new query session with the Qwen Code.

Parameters

• prompt: string | AsyncIterable<SDKUserMessage> - The prompt to send. Use a string for single-turn queries or an async iterable for multi-turn conversations.
• options: QueryOptions - Configuration options for the query session.

QueryOptions

[!note]
For coreTools, aliases like Read, Edit, and Bash also work, but invocation specifiers such as Bash(git *) are stripped. coreTools restricts tool registration, not invocation patterns.

Empty core-tool allowlists

An omitted or empty coreTools list is treated as unspecified; coreTools: [] does not create a tool-free session. A non-empty list restricts core tools, not every tool category: MCP and other non-core tools have separate registration and permission rules. Use excludeTools to exclude named tools explicitly. allowedTools controls approval, not which tools are registered.

Timeouts Copy Section

The SDK enforces the following default timeouts:

You can customize these timeouts via the timeout option:

import { query } from '@qwen-code/sdk';

const q = query({
  prompt: 'Your prompt',
  options: {
    timeout: {
      canUseTool: 60000, // 60 seconds for permission callback
      mcpRequest: 600000, // 10 minutes for MCP tool calls
      controlRequest: 60000, // 60 seconds for control requests
      streamClose: 15000, // 15 seconds for stream close wait
    },
  },
});

Message Types Copy Section

The SDK provides type guards to identify different message types:

import {
  isSDKUserMessage,
  isSDKAssistantMessage,
  isSDKSystemMessage,
  isSDKResultMessage,
  isSDKPartialAssistantMessage,
} from '@qwen-code/sdk';

for await (const message of result) {
  if (isSDKAssistantMessage(message)) {
    // Handle assistant message
  } else if (isSDKResultMessage(message)) {
    // Handle result message
  }
}

Query Instance Methods Copy Section

The Query instance returned by query() provides several methods:

const q = query({ prompt: 'Hello', options: {} });

// Get session ID
const sessionId = q.getSessionId();

// Check if closed
const closed = q.isClosed();

// Interrupt the current operation
await q.interrupt();

// Change permission mode mid-session
await q.setPermissionMode('yolo');

// Change model mid-session
await q.setModel('qwen-max');

// Get context window usage breakdown (token counts per category)
const usage = await q.getContextUsage();
// Pass true to hint that per-item details should be displayed
const detail = await q.getContextUsage(true);

// Close the session
await q.close();

interrupt() cancels only the active turn. For a multi-turn query created with
an async iterable prompt, the query and its input stream remain open, so later
messages from the iterable are processed normally. Use close() or abort the
configured AbortController when you want to end the entire session.

Daemon caller-supplied session IDs Copy Chapter

DaemonClient.createOrAttachSession accepts an optional sessionId for callers that must persist an identity before session creation:

import { DaemonClient } from '@qwen-code/sdk';

const daemon = new DaemonClient({ baseUrl: 'http://127.0.0.1:4170' });
const session = await daemon.createOrAttachSession({
  workspaceCwd: '/path/to/project',
  sessionId: '550E8400-E29B-41D4-A716-446655440000',
});

console.log(session.sessionId); // 550e8400-e29b-41d4-a716-446655440000

The SDK requires the daemon's session_id_override capability before sending the mutation. REST mode serializes sessionId directly; an active ACP adapter maps it to session/new._meta["qwen-code/sessionId"]. The SDK verifies the success response and throws DaemonSessionIdProtocolError if the daemon returns a different ID.

This option always creates a new thread session and is not an idempotent attach. If the create outcome is ambiguous, use the known ID with load or resume. Omitting the option preserves the existing create-or-attach behavior.

Daemon startup model and reasoning selection Copy Chapter

DaemonClient.createOrAttachSession and createStandaloneSession accept startupConfig: { modelServiceId, reasoningEffort? } and preflight session_startup_config before creation. The model is required; omit reasoning for model-only selection, including models with no reasoning control. An explicit effort is validated against the model. The SDK checks modelApplied: true and the canonical startupConfigApplied response; model-only confirmation omits reasoning fields.

Startup selection does not save shared defaults or impose a lifetime pin. Definite selection rejection fails creation; uncertain standalone creation retains its existing recovery result. A successful response whose startup confirmation is missing or mismatched is rejected directly and does not trigger standalone recovery/adoption. See the protocol.

Talking to running sessions Copy Chapter

@qwen-code/sdk/peer lets a program that is not a Qwen Code session join the
sessions running as the same user on the same machine — a voice front-end, a
relay, a build watcher. The program shows up in qwen sessions ps, and in the
list_agents of every session that takes part in cross-session messaging — its
agents.crossSessionMessaging setting is on, and it was not started with
--bare or --safe-mode — which is also what lets those sessions message it
by name with send_message. It can message them back. It runs on Node only and
needs nothing beyond Node itself.

import { PeerEndpoint } from '@qwen-code/sdk/peer';

const endpoint = await PeerEndpoint.start({
  name: 'voice-bridge',
  onMessage: (message) =>
    console.log(`${message.fromName}: ${message.content}`),
});

const [session] = await endpoint.list();
if (session) {
  const sent = await endpoint.send({
    to: session.address,
    content: 'What are you working on?',
  });
  if (sent.kind === 'sent') {
    const receipt = await endpoint.awaitReceipt(sent.msgId, { final: true });
    console.log(receipt?.status); // delivered, denied, refused, ...
  }
}

await endpoint.close();

A message like that is held for the session's user to review. To direct a
session without that review, mint a controller token with
qwen sessions controllers add --label voice-bridge, give it to the endpoint,
and mark the sends that should present it:

const endpoint = await PeerEndpoint.start({
  name: 'voice-bridge',
  controllerToken: process.env['QWEN_CONTROLLER_TOKEN'],
});
await endpoint.send({
  to: 'my-app-3f',
  content: 'run the tests',
  controller: true,
});

Things to know:

• A session has an inbox only while its agents.crossSessionMessaging setting
  is on, which it is by default, and it was not started with --bare or
  --safe-mode — those turn messaging off whatever the setting says. A session
  that turned it off does not appear in list(), and its own list_agents and
  send_message cannot see or reach the program either. qwen sessions ps
  lists the program regardless.
• A message is delivered without review in exactly two cases: the send
  presents a controller token (controller: true), or its fromMode names the
  receiving session's own review class. fromMode is a claim nothing
  authenticates, so a program that is not a coding session should leave it
  out. Nothing in the record — not kind, not name — buys delivery. The
  receiving session's agents.crossSessionInbound setting outranks both:
  hold or refuse there wins over a controller token.
• Mark only the sends meant to direct a session. Addresses are resolved from
  records any program running as you can write, so a controller send presents
  the token to whichever process's record answers to that address. A
  controller send to another peer endpoint is dropped unread, because an
  endpoint's inbox accepts only its own token.
• The endpoint's inbox applies none of the protections a Qwen Code session
  applies to its own: no rate limit, no holds, and no duplicate window beyond
  the last 200 messages it answered. Every message is answered delivered and
  handed to onMessage as it arrives, so apply your own limits there if you
  need them. Without onMessage, every message is answered refused.
• Call close() before exiting, including from your own signal handlers. A
  process killed without closing leaves its record behind until a Qwen Code
  session lists the directory and sees the process is gone.
• UNIX domain sockets only: Windows is not supported yet.

The record schema, wire format and receipt states are documented in
Cross-Session Protocol.

Permission Modes Copy Chapter

The SDK supports different permission modes for controlling tool execution:

• default: Write tools are denied unless approved via canUseTool callback or in allowedTools. Read-only tools execute without confirmation.
• plan: Blocks all write tools, instructing AI to present a plan first.
• auto-edit: Auto-approve edit tools (edit, write_file, notebook_edit) while other tools require confirmation.
• auto: Uses the built-in classifier to auto-approve safe tool calls and block risky ones, with manual-approval fallback after repeated policy blocks or classifier outages.
• yolo: All tools execute automatically without confirmation.

Permission Priority Chain Copy Section

Decision priority (highest first): deny > ask > allow > (default/interactive mode)

The first matching rule wins.

1. excludeTools / permissions.deny - Blocks tools completely (returns permission error)
2. permissions.ask - Always requires user confirmation
3. permissionMode: 'plan' - Blocks all non-read-only tools
4. permissionMode: 'yolo' - Auto-approves all tools
5. allowedTools / permissions.allow - Auto-approves matching tools
6. permissionMode: 'auto' - Classifier-mediated approval for remaining tools
7. canUseTool callback - Custom approval logic (if provided, not called for allowed tools)
8. Default behavior - Auto-deny in SDK mode (write tools require explicit approval)

Examples Copy Chapter

Multi-turn Conversation Copy Section

import { query, type SDKUserMessage } from '@qwen-code/sdk';

async function* generateMessages(): AsyncIterable<SDKUserMessage> {
  yield {
    type: 'user',
    session_id: 'my-session',
    message: { role: 'user', content: 'Create a hello.txt file' },
    parent_tool_use_id: null,
  };

  // Wait for some condition or user input
  yield {
    type: 'user',
    session_id: 'my-session',
    message: { role: 'user', content: 'Now read the file back' },
    parent_tool_use_id: null,
  };
}

const result = query({
  prompt: generateMessages(),
  options: {
    permissionMode: 'auto-edit',
  },
});

for await (const message of result) {
  console.log(message);
}

Custom Permission Handler Copy Section

import { query, type CanUseTool } from '@qwen-code/sdk';

const canUseTool: CanUseTool = async (toolName, input, { signal }) => {
  // Allow all read operations
  if (toolName.startsWith('read_')) {
    return { behavior: 'allow', updatedInput: input };
  }

  // Prompt user for write operations (in a real app)
  const userApproved = await promptUser(`Allow ${toolName}?`);

  if (userApproved) {
    return { behavior: 'allow', updatedInput: input };
  }

  return { behavior: 'deny', message: 'User denied the operation' };
};

const result = query({
  prompt: 'Create a new file',
  options: {
    canUseTool,
  },
});

With External MCP Servers Copy Section

import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'Use the custom tool from my MCP server',
  options: {
    mcpServers: {
      'my-server': {
        command: 'node',
        args: ['path/to/mcp-server.js'],
        env: { PORT: '3000' },
      },
    },
  },
});

Override the System Prompt Copy Section

import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'Say hello in one sentence.',
  options: {
    systemPrompt: 'You are a terse assistant. Answer in exactly one sentence.',
  },
});

Append to the Built-in System Prompt Copy Section

import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'Review the current directory.',
  options: {
    systemPrompt: {
      type: 'preset',
      preset: 'qwen_code',
      append: 'Be terse and focus on concrete findings.',
    },
  },
});

With SDK-Embedded MCP Servers Copy Section

The SDK provides tool and createSdkMcpServer to create MCP servers that run in the same process as your SDK application. This is useful when you want to expose custom tools to the AI without running a separate server process.

`tool(name, description, inputSchema, handler)`

Creates a tool definition with Zod schema type inference.

The handler must return a CallToolResult object with the following structure:

{
  content: Array<
    | { type: 'text'; text: string }
    | { type: 'image'; data: string; mimeType: string }
    | { type: 'resource'; uri: string; mimeType?: string; text?: string }
  >;
  isError?: boolean;
}

`createSdkMcpServer(options)`

Creates an SDK-embedded MCP server instance.

Returns a McpSdkServerConfigWithInstance object that can be passed directly to the mcpServers option.

Example

import { z } from 'zod';
import { query, tool, createSdkMcpServer } from '@qwen-code/sdk';

// Define a tool with Zod schema
const calculatorTool = tool(
  'calculate_sum',
  'Add two numbers',
  { a: z.number(), b: z.number() },
  async (args) => ({
    content: [{ type: 'text', text: String(args.a + args.b) }],
  }),
);

// Create the MCP server
const server = createSdkMcpServer({
  name: 'calculator',
  tools: [calculatorTool],
});

// Use the server in a query
const result = query({
  prompt: 'What is 42 + 17?',
  options: {
    permissionMode: 'yolo',
    mcpServers: {
      calculator: server,
    },
  },
});

for await (const message of result) {
  console.log(message);
}

Abort a Query Copy Section

import { query, isAbortError } from '@qwen-code/sdk';

const abortController = new AbortController();

const result = query({
  prompt: 'Long running task...',
  options: {
    abortController,
  },
});

// Abort after 5 seconds
setTimeout(() => abortController.abort(), 5000);

try {
  for await (const message of result) {
    console.log(message);
  }
} catch (error) {
  if (isAbortError(error)) {
    console.log('Query was aborted');
  } else {
    throw error;
  }
}

Error Handling Copy Chapter

The SDK provides an AbortError class for handling aborted queries:

import { AbortError, isAbortError } from '@qwen-code/sdk';

try {
  // ... query operations
} catch (error) {
  if (isAbortError(error)) {
    // Handle abort
  } else {
    // Handle other errors
  }
}

Human-origin workflow hints Copy Chapter

Streaming SDKUserMessage input supports per-message origin: { kind: 'human' } for original human submissions. Messages without the declaration and string convenience prompts remain ordinary chat without keyword activation. See the workflow intent contract (简体中文) for examples and exclusions.

Plans 2026 03 22 Agent Tool Display Design (`docs/plans/2026-03-22-agent-tool-display-design.md`) Copy Section

Agent Tool Display Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add a dedicated VSCode/web UI display for Agent tool executions so subagent progress, summaries, and failures render from structured rawOutput instead of falling back to the generic tool card.

Architecture: Preserve ACP rawOutput through the VSCode session/update pipeline into ToolCallData, then let the shared web UI router detect task_execution payloads and render a dedicated AgentToolCall component. Keep the change shared in packages/webui so VSCode and ChatViewer stay aligned.

Tech Stack: TypeScript, React, Vitest, shared @qwen-code/webui tool-call components.

Task 1: Lock in the failing data-flow behavior Copy Section

Files:

• Modify: packages/vscode-ide-companion/src/services/qwenSessionUpdateHandler.test.ts
• Create: packages/vscode-ide-companion/src/webview/hooks/useToolCalls.test.tsx

Step 1: Write the failing tests

• Add a session handler test asserting tool_call_update forwards rawOutput when ACP sends a task_execution payload.
• Add a hook test asserting useToolCalls stores and updates rawOutput for an agent tool call.

Step 2: Run test to verify it fails

Run: npm test --workspace=packages/vscode-ide-companion -- --run qwenSessionUpdateHandler.test.ts useToolCalls.test.tsx

Expected: failures because rawOutput is not preserved in the current handler/hook pipeline.

Task 2: Lock in the failing renderer behavior Copy Section

Files:

• Create: packages/vscode-ide-companion/src/webview/components/messages/toolcalls/index.test.tsx

Step 1: Write the failing test

• Render the routed tool call with kind: 'other' plus rawOutput.type === 'task_execution'.
• Assert the task description, active child tool, summary, and failure reason render from a dedicated agent display instead of generic text output.

Step 2: Run test to verify it fails

Run: npm test --workspace=packages/vscode-ide-companion -- --run packages/vscode-ide-companion/src/webview/components/messages/toolcalls/index.test.tsx

Expected: failure because the router only keys off kind and no dedicated agent component exists.

Task 3: Preserve structured agent output end-to-end Copy Section

Files:

• Modify: packages/vscode-ide-companion/src/types/chatTypes.ts
• Modify: packages/vscode-ide-companion/src/services/qwenSessionUpdateHandler.ts
• Modify: packages/vscode-ide-companion/src/webview/hooks/useToolCalls.ts
• Modify: packages/webui/src/components/toolcalls/shared/types.ts

Step 1: Implement the minimal data model changes

• Add optional rawOutput to the VSCode session/webview tool-call types.
• Forward rawOutput in QwenSessionUpdateHandler.
• Store/merge rawOutput in useToolCalls.
• Expose rawOutput in shared web UI tool-call data types.

Step 2: Run the focused tests

Run: npm test --workspace=packages/vscode-ide-companion -- --run qwenSessionUpdateHandler.test.ts useToolCalls.test.tsx

Expected: pass.

Task 4: Add the shared agent tool-call UI Copy Section

Files:

• Create: packages/webui/src/components/toolcalls/AgentToolCall.tsx
• Modify: packages/webui/src/components/toolcalls/index.ts
• Modify: packages/vscode-ide-companion/src/webview/components/messages/toolcalls/index.tsx
• Modify: packages/webui/src/components/ChatViewer/ChatViewer.tsx

Step 1: Implement the minimal renderer

• Add a guard for rawOutput.type === 'task_execution'.
• Render task description as the header.
• Show agent name + status, currently running child tools, completion summary, and failure/cancel reason.
• Keep the layout compatible with multiple parallel agent cards by rendering each tool call independently.

Step 2: Run the focused renderer test

Run: npm test --workspace=packages/vscode-ide-companion -- --run packages/vscode-ide-companion/src/webview/components/messages/toolcalls/index.test.tsx

Expected: pass.

Task 5: Verify the integrated surface Copy Section

Files:

• Modify: packages/webui/src/index.ts

Step 1: Export the new shared component if needed

• Re-export any new component/types needed by VSCode or ChatViewer.

Step 2: Run package verification

Run: npm test --workspace=packages/vscode-ide-companion -- --run qwenSessionUpdateHandler.test.ts useToolCalls.test.tsx packages/vscode-ide-companion/src/webview/components/messages/toolcalls/index.test.tsx
Run: npm run check-types --workspace=packages/vscode-ide-companion
Run: npm run typecheck --workspace=packages/webui

Expected: all targeted tests and typechecks pass.

Users Common Workflow (`docs/users/common-workflow.md`) Copy Section

Common workflows

Learn about common workflows with Qwen Code.

Each task in this document includes clear instructions, example commands, and best practices to help you get the most from Qwen Code.

Understand new codebases Copy Chapter

Get a quick codebase overview Copy Section

Suppose you've just joined a new project and need to understand its structure quickly.

1. Navigate to the project root directory

cd /path/to/project

2. Start Qwen Code

qwen

3. Ask for a high-level overview

give me an overview of this codebase

4. Dive deeper into specific components

explain the main architecture patterns used here

what are the key data models?

how is authentication handled?

[!tip]

• Start with broad questions, then narrow down to specific areas
• Ask about coding conventions and patterns used in the project
• Request a glossary of project-specific terms

Find relevant code Copy Section

Suppose you need to locate code related to a specific feature or functionality.

1. Ask Qwen Code to find relevant files

find the files that handle user authentication

2. Get context on how components interact

how do these authentication files work together?

3. Understand the execution flow

trace the login process from front-end to database

[!tip]

• Be specific about what you're looking for
• Use domain language from the project

Fix bugs efficiently Copy Chapter

Suppose you've encountered an error message and need to find and fix its source.

1. Share the error with Qwen Code

I'm seeing an error when I run npm test

2. Ask for fix recommendations

suggest a few ways to fix the @ts-ignore in user.ts

3. Apply the fix

update user.tsto add the null check you suggested

[!tip]

• Tell Qwen Code the command to reproduce the issue and get a stack trace
• Mention any steps to reproduce the error
• Let Qwen Code know if the error is intermittent or consistent

Refactor code Copy Chapter

Suppose you need to update old code to use modern patterns and practices.

1. Identify legacy code for refactoring

find deprecated API usage in our codebase

2. Get refactoring recommendations

suggest how to refactor utils.js to use modern JavaScript features

3. Apply the changes safely

refactor utils.js to use ES 2024 features while maintaining the same behavior

4. Verify the refactoring

run tests for the refactored code

[!tip]

• Ask Qwen Code to explain the benefits of the modern approach
• Request that changes maintain backward compatibility when needed
• Do refactoring in small, testable increments

Use specialized subagents Copy Chapter

Suppose you want to use specialized AI subagents to handle specific tasks more effectively.

1. View available subagents

/agents

This shows all available subagents and lets you create new ones.

2. Use subagents automatically

Qwen Code automatically delegates appropriate tasks to specialized subagents:

review my recent code changes for security issues

run all tests and fix any failures

3. Explicitly request specific subagents

use the code-reviewer subagent to check the auth module

have the debugger subagent investigate why users can't log in

4. Create custom subagents for your workflow

/agents

Then select "create" and follow the prompts to define:

• A unique identifier that describes the subagent's purpose (for example, code-reviewer, api-designer).
• When Qwen Code should use this agent
• Which tools it can access
• A system prompt describing the agent's role and behavior

[!tip]

• Create project-specific subagents in .qwen/agents/ for team sharing
• Use descriptive description fields to enable automatic delegation
• Limit tool access to what each subagent actually needs
• Know more about Sub Agents
• Know more about Approval Mode

Work with tests Copy Chapter

Suppose you need to add tests for uncovered code.

1. Identify untested code

find functions in NotificationsService.swift that are not covered by tests

2. Generate test scaffolding

add tests for the notification service

3. Add meaningful test cases

add test cases for edge conditions in the notification service

4. Run and verify tests

run the new tests and fix any failures

Qwen Code can generate tests that follow your project's existing patterns and conventions. When asking for tests, be specific about what behavior you want to verify. Qwen Code examines your existing test files to match the style, frameworks, and assertion patterns already in use.

For comprehensive coverage, ask Qwen Code to identify edge cases you might have missed. Qwen Code can analyze your code paths and suggest tests for error conditions, boundary values, and unexpected inputs that are easy to overlook.

Create pull requests Copy Chapter

Suppose you need to create a well-documented pull request for your changes.

1. Summarize your changes

summarize the changes I've made to the authentication module

2. Generate a pull request with Qwen Code

create a pr

3. Review and refine

enhance the PR description with more context about the security improvements

4. Add testing details

add information about how these changes were tested

[!tip]

• Ask Qwen Code directly to make a PR for you
• Review Qwen Code's generated PR before submitting
• Ask Qwen Code to highlight potential risks or considerations

Handle documentation Copy Chapter

Suppose you need to add or update documentation for your code.

1. Identify undocumented code

find functions without proper JSDoc comments in the auth module

2. Generate documentation

add JSDoc comments to the undocumented functions in auth.js

3. Review and enhance

improve the generated documentation with more context and examples

4. Verify documentation

check if the documentation follows our project standards

[!tip]

• Specify the documentation style you want (JSDoc, docstrings, etc.)
• Ask for examples in the documentation
• Request documentation for public APIs, interfaces, and complex logic

Reference files and directories Copy Chapter

Use @ to quickly include files or directories without waiting for Qwen Code to read them.

1. Reference a single file

Explain the logic in @src/utils/auth.js

This includes the full content of the file in the conversation.

2. Reference a directory

What's the structure of @src/components?

This provides a directory listing with file information.

3. Reference MCP resources

Show me the data from @github: repos/owner/repo/issues

This fetches data from connected MCP servers using the format @server: resource. See MCP for details.

[!tip]

• File paths can be relative or absolute
• @ file references add QWEN.md in the file's directory and parent directories to context
• Directory references show file listings, not contents
• You can reference multiple files in a single message (for example, "@file 1.js and @file 2.js")

Resume previous conversations Copy Chapter

Suppose you've been working on a task with Qwen Code and need to continue where you left off in a later session.

Qwen Code provides two options for resuming previous conversations:

• --continue to automatically continue the most recent conversation
• --resume to display a conversation picker

1. Continue the most recent conversation

qwen --continue

This immediately resumes your most recent conversation without any prompts.

2. Continue in non-interactive mode

qwen --continue -p "Continue with my task"

Use -p (or --prompt) with --continue to resume the most recent conversation in non-interactive mode, perfect for scripts or automation.

3. Show conversation picker

qwen --resume

This displays an interactive conversation selector with a clean list view showing:

• Session summary (or initial prompt)
• Metadata: time elapsed, message count, and git branch

Use arrow keys to navigate and press Enter to select a conversation. Press Esc to exit.

[!tip]

• Conversation history is stored locally on your machine
• Use --continue for quick access to your most recent conversation
• Use --resume when you need to select a specific past conversation
• When resuming, you'll see the entire conversation history before continuing
• The resumed conversation starts with the same model and configuration as the original

How it works:

1. Conversation Storage: All conversations are automatically saved locally with their full message history
2. Message Deserialization: When resuming, the entire message history is restored to maintain context
3. Tool State: Tool usage and results from the previous conversation are preserved
4. Context Restoration: The conversation resumes with all previous context intact

Examples:

bash Copy

# Continue most recent conversation
qwen --continue

# Continue most recent conversation with a specific prompt
qwen --continue -p "Show me our progress"

# Show conversation picker
qwen --resume

# Continue most recent conversation in non-interactive mode
qwen --continue -p "Run the tests again"

Run parallel Qwen Code sessions with Git worktrees Copy Chapter

Suppose you need to work on multiple tasks simultaneously with complete code isolation between Qwen Code instances.

1. Understand Git worktrees

Git worktrees allow you to check out multiple branches from the same repository into separate directories. Each worktree has its own working directory with isolated files, while sharing the same Git history. Learn more in the official Git worktree documentation.

2. Create a new worktree

# Create a new worktree with a new branch
git worktree add ../project-feature-a -b feature-a

# Or create a worktree with an existing branch
git worktree add ../project-bugfix bugfix-123

This creates a new directory with a separate working copy of your repository.

3. Run Qwen Code in each worktree

# Navigate to your worktree
cd ../project-feature-a

# Run Qwen Code in this isolated environment
qwen

4. Run Qwen Code in another worktree

cd ../project-bugfix
qwen

5. Manage your worktrees

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../project-feature-a

[!tip]

• Each worktree has its own independent file state, making it perfect for parallel Qwen Code sessions
• Changes made in one worktree won't affect others, preventing Qwen Code instances from interfering with each other
• All worktrees share the same Git history and remote connections
• For long-running tasks, you can have Qwen Code working in one worktree while you continue development in another
• Use descriptive directory names to easily identify which task each worktree is for
• Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include:
  • JavaScript projects: Running dependency installation (npm install, yarn)
  • Python projects: Setting up virtual environments or installing with package managers
  • Other languages: Following your project's standard setup process

Use Qwen Code as a unix-style utility Copy Chapter

Add Qwen Code to your verification process Copy Section

Suppose you want to use Qwen Code as a linter or code reviewer.

Add Qwen Code to your build script:

// package.json
{
    ...
    "scripts": {
        ...
        "lint:Qwen Code": "qwen -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'"
    }
}

[!tip]

• Use Qwen Code for automated code review in your CI/CD pipeline
• Customize the prompt to check for specific issues relevant to your project
• Consider creating multiple scripts for different types of verification

Pipe in, pipe out Copy Section

Suppose you want to pipe data into Qwen Code, and get back data in a structured format.

Pipe data through Qwen Code:

cat build-error.txt | qwen -p 'concisely explain the root cause of this build error' > output.txt

[!tip]

• Use pipes to integrate Qwen-Code into existing shell scripts
• Combine with other Unix tools for powerful workflows
• Consider using --output-format for structured output

Control output format Copy Section

Suppose you need Qwen Code's output in a specific format, especially when integrating Qwen Code into scripts or other tools.

1. Use text format (default)

cat data.txt | qwen -p 'summarize this data' --output-format text > summary.txt

This outputs just Qwen Code's plain text response (default behavior).

2. Use JSON format

cat code.py | qwen -p 'analyze this code for bugs' --output-format json > analysis.json

This outputs a JSON array of messages with metadata including cost and duration.

3. Use streaming JSON format

cat log.txt | qwen -p 'parse this log file for errors' --output-format stream-json

This outputs a series of JSON objects in real-time as Qwen Code processes the request. Each message is a valid JSON object, but the entire output is not valid JSON if concatenated.

[!tip]

• Use --output-format text for simple integrations where you just need Qwen Code's response
• Use --output-format json when you need the full conversation log
• Use --output-format stream-json for real-time output of each conversation turn

Ask Qwen Code about its capabilities Copy Chapter

Qwen Code has built-in access to its documentation and can answer questions about its own features and limitations.

Example questions Copy Section

can Qwen Code create pull requests?

how does Qwen Code handle permissions?

what slash commands are available?

how do I use MCP with Qwen Code?

how do I configure Qwen Code for Amazon Bedrock?

what are the limitations of Qwen Code?

[!note]

Qwen Code provides documentation-based answers to these questions. For executable examples and hands-on demonstrations, refer to the specific workflow sections above.

[!tip]

• Qwen Code always has access to the latest Qwen Code documentation, regardless of the version you're using
• Ask specific questions to get detailed answers
• Qwen Code can explain complex features like MCP integration, enterprise configurations, and advanced workflows

Reuse saved workflows in a monorepo Copy Chapter

With tools.workflowsEnabled enabled, a local terminal, headless, or direct ACP session can use saved workflows from trusted parent directories in the same Git repository. For example, when you start Qwen Code in repo/packages/app, a workflow named review is selected in this order:

repo/packages/app/.qwen/workflows/review.js
repo/packages/.qwen/workflows/review.js
repo/.qwen/workflows/review.js
~/.qwen/workflows/review.js

The nearest definition wins. Parent discovery stops at the closest Git root, including a worktree or submodule root. A directory outside a Git repository keeps its own project and user workflows. Extension workflows retain their qualified names, such as gcp:review.

Folder trust follows the operator's settings; workspace settings cannot enable or disable this ancestor check. When folder trust is enabled, the current target and each parent must be trusted by the saved folder-trust rules. Trusting only the current directory does not grant access to its parents; an unknown or denied parent stops the search toward the root. IDE trust alone does not grant parent access. Changes to the folder-trust file take effect on the next discovery or script lookup, so a previously listed command cannot use its cached path to read a parent whose trust was revoked. Refresh the command list or start a new session to see added or removed commands. When folder trust is disabled, local sessions allow parent discovery within the Git boundary. On POSIX systems, this disabled mode still excludes parents whose directory, .qwen, or workflow directory is writable by everyone. Windows permission bits do not describe ACLs, so this POSIX permission check does not apply there.

Parent workflows still require the usual workflow approval, which identifies the selected script. Content changes invalidate approvals pinned to the script's digest. Running a parent's workflow keeps the session's working directory, and saving to project scope writes to the current session's .qwen/workflows/ directory.

Daemon-managed ACP children, Web Shell, hosted sessions, and restricted sessions do not opt into parent discovery. Parent directories and their workflow files must be ordinary directories and files; symbolic links cannot grant access to a parent workflow.

Enforce evidence-based conclusions Copy Chapter

When Qwen Code does high-stakes work — code review, incident troubleshooting, audits, or investigating production data — a confident but wrong conclusion costs more than no conclusion at all. You can encode your team's verification policy in QWEN.md (see Memory) so it applies to every session, without changing anyone's defaults.

The rules below are adapted from a production retrospective of a multi-agent deployment, where confident-but-wrong conclusions repeatedly traced back to the same failure modes: inferring state from code instead of querying it, treating one satisfied condition as proof, and repeating earlier statements as facts.

1. Add a verification policy to your project QWEN.md

Put this template in QWEN.md at your repository root and commit it, so the policy applies to the whole team:

# Verification policy

Treat these rules as mandatory in investigations, troubleshooting, reviews, and any task that draws conclusions:

1. Verify before concluding. Back claims about data or system state with evidence from the authoritative source (database, API, logs, command output). Conclusions drawn from reading code alone must be labeled "unverified inference".
2. Verify the full chain. Enumerate the causal chain and check every link; one satisfied necessary condition does not prove a conclusion.
3. Treat conversation history as leads, not facts. Statements in earlier transcripts — including your own prior assertions — are leads. Re-verify them at the source before repeating them as facts.
4. Troubleshoot in order: your own recent changes first, then docs and known issues, and only then external dependencies.
5. 100% evidence rule in reviews. In review and audit tasks, report no conclusion without evidence; attach verifiable evidence (file:line, query result, log excerpt) to every claim.

2. Choose the right scope

See Where to create QWEN.md for which file applies to whom — commit the project-root QWEN.md copy so the policy covers the whole team.

[!tip]

• Keep the rules specific and actionable: "back every claim with a query result" works better than "be careful".
• Keep the policy short — QWEN.md is followed more reliably when it is concise (see Memory).
• Adapt the rules to your stack: name the actual query tools, dashboards, or log commands your team treats as authoritative sources.

Suggest a workflow for one human turn Copy Chapter

Use ultracode or the existing workflow keyword in a supported human submission to suggest the Workflow tool for that turn. See workflow intent (简体中文) for entry points, SDK opt-in, and settings.

Users Integration Github Action (`docs/users/integration-github-action.md`) Copy Section

GitHub Actions：qwen-code-action

Overview Copy Chapter

qwen-code-action is a GitHub Action that integrates Qwen Code into your development workflow via the Qwen Code CLI. It acts both as an autonomous agent for critical routine coding tasks, and an on-demand collaborator you can quickly delegate work to.

Use it to perform GitHub pull request reviews, triage issues, perform code analysis and modification, and more using Qwen Code conversationally (e.g., @qwencoder fix this issue) directly inside your GitHub repositories.

Features Copy Chapter

• Automation: Trigger workflows based on events (e.g. issue opening) or schedules (e.g. nightly).
• On-demand Collaboration: Trigger workflows in issue and pull request
  comments by mentioning the Qwen Code CLI (e.g., @qwencoder /review).
• Extensible with Tools: Leverage Qwen Code models' tool-calling capabilities to interact with other CLIs like the GitHub CLI (gh).
• Customizable: Use a QWEN.md file in your repository to provide
  project-specific instructions and context to Qwen Code CLI.

Quick Start Copy Chapter

Get started with Qwen Code CLI in your repository in just a few minutes:

1. Get a Qwen API Key Copy Section

Obtain your API key from DashScope (Alibaba Cloud's AI platform)

2. Add it as a GitHub Secret Copy Section

Store your API key as a secret named QWEN_API_KEY in your repository:

• Go to your repository's Settings > Secrets and variables > Actions
• Click New repository secret
• Name: QWEN_API_KEY, Value: your API key

3. Update your .gitignore Copy Section

Add the following entries to your .gitignore file:

# qwen-code-cli settings
.qwen/

# GitHub App credentials
gha-creds-*.json

4. Choose a Workflow Copy Section

You have two options to set up a workflow:

Option A: Use setup command (Recommended)

1. Start the Qwen Code CLI in your terminal:

   shell Copy

   qwen

2. In Qwen Code CLI in your terminal, type:

   text Copy

   /setup-github

Option B: Manually copy workflows

1. Copy the pre-built workflows from the examples/workflows directory to your repository's .github/workflows directory. Note: the qwen-dispatch.yml workflow must also be copied, which triggers the workflows to run.

5. Try it out Copy Section

Pull Request Review:

• Open a pull request in your repository and wait for automatic review
• Comment @qwencoder /review on an existing pull request to manually trigger a review

Issue Triage:

• Open an issue and wait for automatic triage
• Comment @qwencoder /triage on existing issues to manually trigger triaging

General AI Assistance:

• In any issue or pull request, mention @qwencoder followed by your request
• Examples:
  • @qwencoder explain this code change
  • @qwencoder suggest improvements for this function
  • @qwencoder help me debug this error
  • @qwencoder write unit tests for this component

Workflows Copy Chapter

This action provides several pre-built workflows for different use cases. Each workflow is designed to be copied into your repository's .github/workflows directory and customized as needed.

Qwen Code Dispatch Copy Section

This workflow acts as a central dispatcher for Qwen Code CLI, routing requests to the appropriate workflow based on the triggering event and the command provided in the comment. For a detailed guide on how to set up the dispatch workflow, go to the Qwen Code Dispatch workflow documentation.

Issue Triage Copy Section

This action can be used to triage GitHub Issues automatically or on demand. For a working issue triage setup, see the Qwen triage workflow.

Pull Request Review Copy Section

This action can be used to automatically review pull requests when they are opened. For a detailed guide on how to set up the pull request review system, go to the GitHub PR Review workflow documentation.

Qwen Code CLI Assistant Copy Section

This type of action can be used to invoke a general-purpose, conversational Qwen Code AI assistant within the pull requests and issues to perform a wide range of tasks. For a detailed guide on how to set up the general-purpose Qwen Code CLI workflow, go to the Qwen Code Assistant workflow documentation.

Configuration Copy Chapter

Inputs Copy Section

• qwen*api_key: *(Optional)_ The API key for the Qwen API.

• qwen*cli_version: *(Optional, default: latest)_ The version of the Qwen Code CLI to install. Can be "latest", "preview", "nightly", a specific version number, or a git branch, tag, or commit. For more information, see Qwen Code CLI releases.

• qwen*debug: *(Optional)_ Enable debug logging and output streaming.

• qwen*model: *(Optional)_ The model to use with Qwen Code.

• prompt: (Optional, default: You are a helpful assistant.) A string passed to the Qwen Code CLI's --prompt argument.

• settings: (Optional) A JSON string written to .qwen/settings.json to configure the CLI's project settings.
  For more details, see the documentation on settings files.

• use*qwen_code_assist: *(Optional, default: false)_ Whether to use Code Assist for Qwen Code model access instead of the default Qwen Code API key.
  For more information, see the Qwen Code CLI documentation.

• use*vertex_ai: *(Optional, default: false)_ Whether to use Vertex AI for Qwen Code model access instead of the default Qwen Code API key.
  For more information, see the Qwen Code CLI documentation.

• extensions: (Optional) A list of Qwen Code CLI extensions to install.

• upload*artifacts: *(Optional, default: false)_ Whether to upload artifacts to the github action.

• use*pnpm: *(Optional, default: false)_ Whether or not to use pnpm instead of npm to install qwen-code-cli

• workflow*name: *(Optional, default: ${{ github.workflow }})_ The GitHub workflow name, used for telemetry purposes.

Outputs Copy Section

• summary: The summarized output from the Qwen Code CLI execution.

• error: The error output from the Qwen Code CLI execution, if any.

Repository Variables Copy Section

We recommend setting the following values as repository variables so they can be reused across all workflows. Alternatively, you can set them inline as action inputs in individual workflows or to override repository-level values.

To add a repository variable:

1. Go to your repository's Settings > Secrets and variables > Actions > New variable.
2. Enter the variable name and value.
3. Save.

For details about repository variables, refer to the GitHub documentation on variables.

Secrets Copy Section

You can set the following secrets in your repository:

To add a secret:

1. Go to your repository's Settings > Secrets and variables >Actions > New repository secret.
2. Enter the secret name and value.
3. Save.

For more information, refer to the official GitHub documentation on creating and using encrypted secrets.

Authentication Copy Chapter

This action requires authentication to the GitHub API and optionally to Qwen Code services.

GitHub Authentication Copy Section

You can authenticate with GitHub in two ways:

1. Default GITHUB_TOKEN: For simpler use cases, the action can use the
   default GITHUB_TOKEN provided by the workflow.
2. Custom GitHub App (Recommended): For the most secure and flexible
   authentication, we recommend creating a custom GitHub App.

For detailed setup instructions for both Qwen and GitHub authentication, go to the
Authentication documentation.

Extensions Copy Chapter

The Qwen Code CLI can be extended with additional functionality through extensions.
These extensions are installed from source from their GitHub repositories.

For detailed instructions on how to set up and configure extensions, go to the
Extensions documentation.

Best Practices Copy Chapter

To ensure the security, reliability, and efficiency of your automated workflows, we strongly recommend following our best practices. These guidelines cover key areas such as repository security, workflow configuration, and monitoring.

Key recommendations include:

• Securing Your Repository: Implementing branch and tag protection, and restricting pull request approvers.
• Monitoring and Auditing: Regularly reviewing action logs and enabling OpenTelemetry for deeper insights into performance and behavior.

For a comprehensive guide on securing your repository and workflows, please refer to our Best Practices documentation.

Customization Copy Chapter

Create a QWEN.md file in the root of your repository to provide
project-specific context and instructions to Qwen Code CLI. This is useful for defining
coding conventions, architectural patterns, or other guidelines the model should
follow for a given repository.

Contributing Copy Chapter

Contributions are welcome! Check out the Qwen Code CLI Contributing Guide for more details on how to get started.

Users Integration Jetbrains (`docs/users/integration-jetbrains.md`) Copy Section

JetBrains IDEs

JetBrains IDEs provide native support for AI coding assistants through the Agent Client Protocol (ACP). This integration allows you to use Qwen Code directly within your JetBrains IDE with real-time code suggestions.

Features Copy Section

• Native agent experience: Integrated AI assistant panel within your JetBrains IDE
• Agent Client Protocol: Full support for ACP enabling advanced IDE interactions
• Symbol management: #-mention files to add them to the conversation context
• Conversation history: Access to past conversations within the IDE
• Reasoning effort: Choose Default, Low, Medium, High, Extra high, or Max from the agent's session options; each provider maps or clamps the requested tier for the active model
• Context usage: See the current context-window occupancy while Qwen Code works

Requirements Copy Section

• JetBrains IDE with ACP support (IntelliJ IDEA, WebStorm, PyCharm, etc.)
• Qwen Code CLI installed

Installation Copy Section

Install from ACP Registry (Recommend)

1. Install Qwen Code CLI:

   bash Copy

   npm install @qwen-code/qwen-code

2. Open your JetBrains IDE and navigate to AI Chat tool window.

3. Click Add ACP Agent, then click Install.

   For users using JetBrains AI Assistant and/or other ACP agents, click Install From ACP Registry in Agents List, then install Qwen Code ACP.

4. The Qwen Code agent should now be available in the AI Assistant panel.

Manual Install (for older version of JetBrains IDEs)

1. Install Qwen Code CLI:

   bash Copy

   npm install @qwen-code/qwen-code

2. Open your JetBrains IDE and navigate to AI Chat tool window.

3. Click the 3-dot menu in the upper-right corner and select Configure ACP Agent and configure Qwen Code with the following settings:

{
  "agent_servers": {
    "qwen": {
      "command": "/path/to/qwen",
      "args": ["--acp"],
      "env": {}
    }
  }
}

4. The Qwen Code agent should now be available in the AI Assistant panel

Troubleshooting Copy Chapter

Agent not appearing Copy Section

• Run qwen --version in terminal to verify installation
• Ensure your JetBrains IDE version supports ACP
• Restart your JetBrains IDE

Qwen Code not responding Copy Section

• Check your internet connection
• Verify CLI works by running qwen in terminal
• File an issue on GitHub if the problem persists

Users Integration Vscode (`docs/users/integration-vscode.md`) Copy Section

Visual Studio Code

The VS Code extension (Beta) lets you see Qwen's changes in real-time through a native graphical interface integrated directly into your IDE, making it easier to access and interact with Qwen Code.

Features Copy Section

• Native IDE experience: Dedicated Qwen Code sidebar panel accessed via the Qwen icon
• Auto-accept edits mode: Automatically apply Qwen's changes as they're made
• File management: @-mention files or attach files and images using the system file picker
• Conversation history: Access to past conversations
• Multiple sessions: Run multiple Qwen Code sessions simultaneously

Requirements Copy Section

• VS Code 1.96.0 or higher

Installation Copy Section

Download and install the extension from the Visual Studio Code Extension Marketplace.

Troubleshooting Copy Chapter

Extension not installing Copy Section

• Ensure you have VS Code 1.96.0 or higher
• Check that VS Code has permission to install extensions
• Try installing directly from the Marketplace website

Qwen Code not responding Copy Section

• Check your internet connection
• Start a new conversation to see if the issue persists
• File an issue on GitHub if the problem continues

Users Integration Zed (`docs/users/integration-zed.md`) Copy Section

Zed Editor

Zed Editor provides native support for AI coding assistants through the Agent Client Protocol (ACP). This integration allows you to use Qwen Code directly within Zed's interface with real-time code suggestions.

Features Copy Section

• Native agent experience: Integrated AI assistant panel within Zed's interface
• Agent Client Protocol: Full support for ACP enabling advanced IDE interactions
• File management: @-mention files to add them to the conversation context
• Conversation history: Access to past conversations within Zed

Requirements Copy Section

• Zed Editor (latest version recommended)
• Qwen Code CLI installed

Installation Copy Section

Install from ACP Registry (Recommend)

1. Install Qwen Code CLI:

npm install @qwen-code/qwen-code

2. Download and install Zed Editor

3. In Zed, click the settings button in the top right corner, select "Add agent", choose "Install from Registry", find Qwen Code, then click Install.

Manual Install

1. Install Qwen Code CLI:

npm install @qwen-code/qwen-code

2. Download and install Zed Editor

3. In Zed, click the settings button in the top right corner, select "Add agent", choose "Create a custom agent", and add the following configuration:

"Qwen Code": {
  "type": "custom",
  "command": "qwen",
  "args": ["--acp"],
  "env": {}
}

Troubleshooting Copy Chapter

Agent not appearing Copy Section

• Run qwen --version in terminal to verify installation
• Check that the JSON configuration is valid
• Restart Zed Editor

Qwen Code not responding Copy Section

• Check your internet connection
• Verify CLI works by running qwen in terminal
• File an issue on GitHub if the problem persists

Design Fork Subagent Fork Subagent Design (`docs/design/fork-subagent/fork-subagent-design.md`) Copy Section

Fork Subagent Design

Implicit fork subagent that inherits the parent's full conversation context and shares prompt cache for cost-efficient parallel task execution.

Overview Copy Chapter

When the Agent tool is called without subagent_type, it triggers an implicit fork — a background subagent that inherits the parent's conversation history, system prompt, and tool definitions. The fork uses CacheSafeParams to ensure its API requests share the same prefix as the parent's, enabling DashScope prompt cache hits.

Architecture Copy Chapter

Parent conversation: [SystemPrompt | Tools | Msg1 | Msg2 | ... | MsgN (model)]
                              ↑ identical prefix for all forks ↑

Fork A: [...MsgN | placeholder results | "Research A"]  ← shared cache
Fork B: [...MsgN | placeholder results | "Modify B"]    ← shared cache
Fork C: [...MsgN | placeholder results | "Test C"]      ← shared cache

Key Components Copy Chapter

1. FORK_AGENT (`forkSubagent.ts`) Copy Section

Synthetic agent config, not registered in builtInAgents. Has a fallback systemPrompt but in practice uses the parent's rendered system prompt via generationConfigOverride.

2. CacheSafeParams Integration (`agent.ts` + `forkedQuery.ts`) Copy Section

agent.ts (fork path)
  │
  ├── getCacheSafeParams()          ← parent's generationConfig snapshot
  │     ├── generationConfig        ← systemInstruction + tools + temp/topP
  │     └── history                 ← (not used — we build extraHistory instead)
  │
  ├── forkGenerationConfig          ← passed as generationConfigOverride
  └── forkToolsOverride             ← FunctionDeclaration[] extracted from tools
        │
        ▼
  AgentHeadless.execute(context, signal, {
    extraHistory,                   ← parent conversation history
    generationConfigOverride,       ← parent's exact systemInstruction + tools
    toolsOverride,                  ← parent's exact tool declarations
  })
        │
        ▼
  AgentCore.createChat(context, {
    extraHistory,
    generationConfigOverride,       ← bypasses buildChatSystemPrompt()
  })                                   AND skips getInitialChatHistory()
        │                              (extraHistory already has env context)
        ▼
  new GeminiChat(config, generationConfig, startHistory)
                          ↑ byte-identical to parent's config

3. History Construction (`agent.ts` + `forkSubagent.ts`) Copy Section

The fork's extraHistory must end with a model message to maintain Gemini API's user/model alternation when agent-headless sends the task_prompt.

Three cases:

4. Recursive Fork Prevention (`forkSubagent.ts`) Copy Section

isInForkChild() scans conversation history for the <fork-boilerplate> tag. If found, the fork attempt is rejected with an error message.

5. Background Execution (`agent.ts`) Copy Section

Fork uses void executeSubagent() (fire-and-forget) and returns FORK_PLACEHOLDER_RESULT immediately to the parent. Errors in the background task are caught, logged, and reflected in the display state.

Data Flow Copy Chapter

1. Model calls Agent tool (no subagent_type)
2. agent.ts: import forkSubagent.js
3. agent.ts: getCacheSafeParams() → forkGenerationConfig + forkToolsOverride
4. agent.ts: build extraHistory from parent's getHistory(true)
5. agent.ts: build forkTaskPrompt (directive or 'Begin.')
6. agent.ts: createAgentHeadless(FORK_AGENT, ...)
7. agent.ts: void executeSubagent() — background
8. agent.ts: return FORK_PLACEHOLDER_RESULT to parent immediately
9. Background:
   a. AgentHeadless.execute(context, signal, {extraHistory, generationConfigOverride, toolsOverride})
   b. AgentCore.createChat() — uses parent's generationConfig (cache-shared)
   c. runReasoningLoop() — uses parent's tool declarations
   d. Fork executes tools, produces result
   e. updateDisplay() with final status

Graceful Degradation Copy Chapter

If getCacheSafeParams() returns null (first turn, no history yet), the fork falls back to:

• FORK_AGENT.systemPrompt for system instruction
• prepareTools() for tool declarations

This ensures the fork always works, even without cache sharing.

Files Copy Chapter

Design Compact Mode Compact Mode Design (`docs/design/compact-mode/compact-mode-design.md`) Copy Section

Compact Mode Design: Competitive Analysis & Optimization

Historical design. The current Web Shell behavior is documented in
Web Shell compact mode and tool progress.

Ctrl+O compact/verbose mode toggle — competitive analysis with Claude Code, current implementation review, and optimization recommendations.

User documentation: Settings — ui.compactMode.

1. Executive Summary Copy Chapter

Qwen Code and Claude Code both provide a Ctrl+O shortcut for toggling between compact and detailed tool output views, but the design philosophy, default state, and interaction model differ fundamentally. This document provides a deep source-level comparison, identifies UX gaps, and proposes optimizations for Qwen Code.

2. Claude Code Implementation Analysis Copy Chapter

2.1 Architecture Copy Section

Claude Code uses a screen-based approach rather than a component-level rendering toggle:

┌──────────────────────────────────┐
│         AppState (Zustand)       │
│  verbose: boolean (default: false)│
│  screen: 'prompt' | 'transcript' │
└──────────┬───────────────────────┘
           │
     ┌─────┴──────┐
     │  Ctrl+O    │  toggles screen mode
     │  Handler    │  NOT a rendering flag
     └─────┬──────┘
           │
     ┌─────▼──────────────┐
     │    REPL.tsx         │
     │  screen='prompt'  → compact view (default)
     │  screen='transcript'→ detailed view
     └────────────────────┘

2.2 Key Source Files Copy Section

2.3 Design Decisions Copy Section

1. Compact is the default. Users see a clean interface out of the box; detail is opt-in.
2. Session-scoped. verbose resets to false on every new session — Claude Code assumes users generally prefer the compact view and only need details temporarily.
3. Screen-level toggle. Ctrl+O doesn't change how components render; it switches the entire display between a "prompt" screen (compact) and a "transcript" screen (detailed).
4. No frozen snapshot. There is no snapshot freezing concept. When toggling, the display updates immediately with current state.
5. Permission dialogs are separate. Tool approvals are rendered in a dedicated overlay layer that is never affected by the verbose/compact toggle.
6. Per-tool hint. CtrlOToExpand component shows a contextual hint on individual tools when they produce large output, suppressed in sub-agents.

2.4 User Flow Copy Section

Session start → compact mode (default)
     │
     ├─ Tool outputs are summarized in a single line
     ├─ Large tool output shows "(ctrl+o to expand)" hint
     │
     ├─ User presses Ctrl+O
     │     └─→ Screen switches to transcript (detailed view)
     │         └─ User sees all tool output, thinking, etc.
     │
     ├─ User presses Ctrl+O again
     │     └─→ Screen switches back to prompt (compact)
     │
     └─ Session ends → verbose resets to false

3. Qwen Code Implementation Analysis Copy Chapter

3.1 Architecture Copy Section

Qwen Code uses a component-level rendering flag that each UI component reads from context:

┌─────────────────────────────────────┐
│      CompactModeContext             │
│  compactMode: boolean (default: false)│
│  setCompactMode: (v) => void        │
└──────────┬──────────────────────────┘
           │
     ┌─────┴──────┐
     │  Ctrl+O    │  toggles compactMode
     │  Handler    │  persists to settings
     └─────┬──────┘
           │
     ┌─────▼──────────────────┐
     │  Each component reads  │
     │  compactMode and       │
     │  decides how to render │
     └────────────────────────┘
           │
     ┌─────▼──────────────────────────────┐
     │  ToolGroupMessage                   │
     │    showCompact = compactMode        │
     │      && !hasConfirmingTool          │
     │      && !hasErrorTool               │
     │      && !isEmbeddedShellFocused     │
     │      && !isUserInitiated            │
     └────────────────────────────────────┘

3.2 Key Source Files Copy Section

3.3 Design Decisions Copy Section

1. Verbose is the default. Users see all tool output and thinking by default.
2. Persistent preference. compactMode is saved to settings.json and survives across sessions.
3. Component-level rendering. Each component reads compactMode from context and adjusts its own rendering.
4. Force-expand protection. Four conditions override compact mode to ensure critical UI elements are always visible (confirmations, errors, shell, user-initiated).
5. No snapshot freezing. The toggle always shows live output — no frozen snapshots.
6. Settings dialog sync. Toggling compact mode from Settings updates React state immediately via setCompactMode.
7. Non-intrusive discoverability. Compact mode is introduced via the startup Tips rotation rather than a persistent footer indicator, avoiding UI clutter.

3.4 User Flow Copy Section

Session start → verbose mode (default)
     │
     ├─ All tool outputs, thinking, details visible
     │
     ├─ User presses Ctrl+O (or toggles in Settings)
     │     └─→ compactMode = true, persisted
     │         ├─ Tool groups show single-line summary
     │         ├─ Thinking/thought content hidden
     │         └─ Confirmations, errors, shell still expanded
     │
     ├─ User presses Ctrl+O again
     │     └─→ compactMode = false, persisted
     │         └─ All details visible again
     │
     └─ Next session → same mode as last session

4. Key Differences Deep Dive Copy Chapter

4.1 Default Mode Philosophy Copy Section

Analysis: Claude Code's compact default works because its user base is generally experienced developers who trust the tool and don't need to see every tool invocation. Qwen Code's verbose default is appropriate for its earlier stage where building user trust through transparency is important.

4.2 Persistence Model Copy Section

Analysis: Claude Code treats detail viewing as a momentary need — you look, then go back. Qwen Code treats it as a stable preference — some users always want details, others always want compact. Both are valid; Qwen Code's approach is more flexible.

4.3 Confirmation Protection Copy Section

Analysis: Claude Code's architectural separation (overlay layer) is more robust. Qwen Code's force-expand approach is effective but requires each new interactive state to be explicitly added to the condition list.

4.4 Rendering Approach Copy Section

Analysis: Qwen Code's component-level approach is more flexible (e.g., force-expand for specific conditions) but requires more discipline to maintain consistency. Claude Code's screen-level approach is simpler and guarantees consistent behavior.

5. Optimization Recommendations Copy Chapter

5.1 [P0] Keep Verbose as Default — No Change Needed Copy Section

Qwen Code's verbose default is the right choice for its current stage. Users who are new to the tool need transparency to build trust. As the product matures, consider making compact the default (like Claude Code).

5.2 [P1] Per-Tool Expansion for Large Outputs Copy Section

Claude Code shows "(ctrl+o to expand)" on individual tools that produce large output. Qwen Code currently only has a global toggle. Consider:

• When a single tool produces output exceeding N lines, show a per-tool "expand" hint in compact mode.
• Scope: future enhancement, not current priority.

5.3 [P2] Consider Session-Scoped Override Copy Section

Some users may want compact mode as their default but occasionally need verbose for a specific session. Consider supporting both:

• settings.json → persistent default (current behavior)
• Ctrl+O during session → temporary override for current session only (Claude Code behavior)
• On session restart → revert to settings.json value

This gives users the best of both worlds. Implementation would require separating "settings default" from "session override" state.

5.4 [P2] Structural Separation for Confirmations Copy Section

Currently, confirmation protection relies on showCompact conditions in ToolGroupMessage. Consider a more robust approach:

• Render confirmations in a separate layer (like Claude Code's overlay approach).
• This would make it architecturally impossible for compact mode to affect confirmations.
• Lower priority since the current force-expand approach works correctly.

6. Current Implementation Status Copy Chapter

After the feat/compact-mode-optimization branch changes:

7. File Reference Copy Chapter

Qwen Code Copy Section

Claude Code (Reference) Copy Section

Design Channels Channels Design (`docs/design/channels/channels-design.md`) Copy Section

Channels Design

External messaging integrations for Qwen Code — interact with an agent from Telegram, WeChat, and more.

User documentation: Channels Overview.

Overview Copy Chapter

A channel connects an external messaging platform to a Qwen Code agent. Configured in settings.json, managed via qwen channel subcommands, multi-user (each user gets an isolated ACP session).

Architecture Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Platform Adapter — connects to external API, translates messages to/from Envelopes. ACP Bridge — spawns qwen-code --acp, manages sessions, emits textChunk/toolCall/disconnected events. Session Router — maps senders to ACP sessions via namespaced keys (<channel>:<sender>). Sender Gate / Group Gate — access control (allowlist / pairing / open) and mention gating. Channel Base — abstract base with Template Method pattern: plugins override connect, sendMessage, disconnect. Channel Registry — Map<string, ChannelPlugin> with collision detection.

Envelope Copy Section

Normalized message format all platforms convert to:

• Identity: senderId, senderName, chatId, channelName
• Content: text, optional imageBase64/imageMimeType, optional referencedText
• Context: isGroup, isMentioned, isReplyToBot, optional threadId

Plugin responsibilities: senderId must be stable/unique; chatId must distinguish DMs from groups; boolean flags must be accurate for gate logic; @mentions stripped from text.

Message Flow Copy Section

Inbound:  User message → Adapter → GroupGate → SenderGate → Slash commands → SessionRouter → AcpBridge → Agent
Outbound: Agent response → AcpBridge → SessionRouter → Adapter → User

Slash commands (/clear, /help, /status) are handled in ChannelBase before reaching the agent.

Sessions Copy Section

One qwen-code --acp process with multiple ACP sessions. Scope per channel: user (default), thread, or single. Routing keys namespaced as <channelName>:<key>.

Error Handling Copy Section

• Connection failures — logged; service continues if at least one channel connects
• Bridge crashes — exponential backoff (max 3 retries), setBridge() on all channels, session restore
• Session serialization — per-session promise chains prevent concurrent prompt collisions

Plugin System Copy Chapter

The architecture is extensible — new adapters (including third-party) can be added without modifying core. Built-in channels use the same plugin interface (dogfooding).

Plugin Contract Copy Section

A ChannelPlugin declares channelType, displayName, requiredConfigFields, and a createChannel() factory. Plugins implement three methods: