命令

本文档详细介绍了 Qwen Code 支持的所有命令，帮助你高效管理会话、自定义界面并控制其行为。

Qwen Code 命令通过特定前缀触发，分为以下三类：

1. 斜杠命令 (/)

斜杠命令用于管理 Qwen Code 的会话、界面和基本行为。

1.1 会话与项目管理

这些命令可帮助你保存、恢复和总结工作进度。

1.2 界面与工作区控制

用于调整界面外观和工作环境的命令。

1.3 语言设置

专门用于控制界面和输出语言的命令。

• 可用的内置 UI 语言：zh-CN（简体中文）、en-US（英语）、ru-RU（俄语）、de-DE（德语）、ja-JP（日语）、pt-BR（葡萄牙语 - 巴西）、fr-FR（法语）、ca-ES（加泰罗尼亚语）
• 输出语言示例：Chinese、English、Japanese 等。

1.4 工具与模型管理

用于管理 AI 工具和模型的命令。

1.5 内置技能

这些命令调用提供专用工作流的捆绑技能。

完整的 /review 文档请参见 Code Review，/autofix-pr 请参见 Autofix a Pull Request。

1.6 侧边提问 (/btw)

/btw 命令允许你快速提出侧边问题，而不会中断或影响主对话流。

工作原理：

• 侧边问题会作为单独的 API 调用发送，并带有最近的对话上下文（最多 20 条消息）
• 响应显示在 Composer 上方——你可以在等待时继续输入
• 主对话不会被阻塞——它会独立继续
• 侧边问题的响应不会成为主对话历史的一部分
• 答案支持完整的 Markdown 渲染（代码块、列表、表格等）

键盘快捷键（交互模式）：

示例：

(While the main conversation is about refactoring code)

> /btw What's the difference between let and var in JavaScript?

  ╭──────────────────────────────────────────╮
  │ /btw What's the difference between let   │
  │     and var in JavaScript?               │
  │                                          │
  │ + Answering...                           │
  │ Press Escape, Ctrl+C, or Ctrl+D to cancel│
  ╰──────────────────────────────────────────╯
  > (Composer remains active — keep typing)

(After the answer arrives)

  ╭──────────────────────────────────────────╮
  │ /btw What's the difference between let   │
  │     and var in JavaScript?               │
  │                                          │
  │ `let` is block-scoped, while `var` is    │
  │ function-scoped. `let` was introduced    │
  │ in ES6 and doesn't hoist the same way.   │
  │                                          │
  │ Press Space, Enter, or Escape to dismiss │
  ╰──────────────────────────────────────────╯
  > (Composer still active)

支持的执行模式：

1.7 第二意见 (/advisor)

/advisor 命令对目前为止的对话进行独立的只读审查，并返回结构化的第二意见——不会执行任务，也不会中断主对话。

工作原理：

• 审查以单独的单轮 API 调用发送，带有最近的对话上下文（最多 40 条消息）
• 审查模型无法执行工具——工具在请求级别被剥离（与 /btw 相同的机制），因此审查永远不会编写代码或运行命令；每个结论都必须基于可见的对话记录
• 主对话不会被中断；审查结果仅展示给你
• 审查渲染为带边框的 markdown 块，包含四个固定部分——裁决、风险、缺失证据和建议——在 /advisor · <model> 标题下标注解析后的审查模型
• 与 /btw 不同，后者是即发即忘且保持会话可用，而 /advisor 会阻塞输入直到审查返回；在完整上下文窗口中使用强审查模型时，这可能需要数十秒
• 默认使用主模型；设置 advisorModel 可将审查路由到不同（通常更强）的模型——最近的对话记录会发送给该模型，即使它使用另一个提供者

示例：

> /advisor is my fix for the null check actually correct?

  Consulting advisor...

  ╭──────────────────────────────────────────────────────╮
  │ /advisor · qwen3-max                                 │
  │                                                      │
  │ Verdict                                              │
  │ The approach is sound, but the edge case at line 42  │
  │ is unverified.                                       │
  │                                                      │
  │ Risks                                                │
  │  - The fix assumes the config is always loaded; a    │
  │    startup race could leave it null.                 │
  │                                                      │
  │ Missing evidence                                     │
  │  - No test exercises the null-config path in the     │
  │    visible transcript.                               │
  │                                                      │
  │ Recommendation                                       │
  │ Add a focused unit test for the null-config branch   │
  │ before merging.                                      │
  ╰──────────────────────────────────────────────────────╯

审查渲染在带边框的框中，其标题标注解析后的审查模型。未知的 advisorModel 不会预先验证——如果提供者拒绝它，/advisor 会报告失败，因此请检查模型名称；只有无法解析的别名选择器（例如 fast 但未配置快速模型）才会回退到主模型。Advisor 请求不使用配置的模型回退。

支持的执行模式：

1.8 会话回顾 (/recap)

/recap 命令会生成当前会话的简短“断点续传”摘要，以便你在无需翻阅大量历史记录的情况下恢复旧对话。

工作原理：

• 如果可用，则使用配置的快速模型（fastModel 设置），否则回退到主会话模型。对于回顾总结而言，一个小型且廉价的模型就足够了。
• 最近的对话（最多 30 条消息，仅文本——工具调用和工具响应会被过滤掉）连同紧凑的系统提示一起发送给模型。
• 回顾内容以暗色显示并带有 ❯ 前缀，以便与真实的助手回复区分开来。
• 如果正在处理模型轮次或另一个命令正在处理中，则会拒绝执行并显示内联错误。如果没有可用的对话，或者底层生成失败，/recap 将显示一条简短的信息消息而不是回顾内容——手动命令始终会有所响应。

从离开状态返回时自动触发：

如果终端失焦 5 分钟以上 并重新获得焦点，系统将自动生成并显示回顾内容（仅当没有模型响应正在进行时；否则它会等待当前轮次完成后再触发）。与手动命令不同，自动触发在失败时完全静默：如果生成出错或没有可总结的内容，不会向历史记录中添加任何消息。由 general.showSessionRecap 设置控制（默认值：false）；无论此设置如何，手动 /recap 命令始终有效。

示例：

> /recap

❯ Refactoring loopDetectionService.ts to address long-session OOM caused by
  unbounded streamContentHistory and contentStats. The next step is to
  implement option B (LRU sliding window with FNV-1a) pending confirmation.

1.9 Diff 查看器 (/diff)

/diff 命令打开一个交互式 diff 查看器，显示未提交的更改和每个轮次的 diff。使用 ←/→ 在当前 git diff 和各个对话轮次之间切换，使用 ↑/↓ 浏览文件，按 Enter 查看内联 diff。

工作原理：

在交互模式下，/diff 会打开一个对话框，顶部带有来源选择器：

• Current — 工作树与 HEAD 对比（git diff HEAD）。显示所有未提交的更改，包括已暂存、未暂存和未跟踪的文件。
• T1, T2, T3, … — 每个轮次的 diff，每个修改了文件的轮次对应一个标签页。最近的轮次显示在最前面。每个标签页会显示原始 prompt 的预览以提供上下文。

文件列表显示每个文件的统计信息（增加/删除的行数），并带有特殊状态的标签（new、deleted、untracked、binary、truncated、oversized）。在文件上按 Enter 可查看其内联 diff，并带有语法高亮的代码块。

每个轮次的 diff 需要启用文件检查点（在交互模式下默认开启）。当文件检查点关闭时，仅”Current”来源可用。

键盘快捷键：

示例：

┌ /diff · Turn 3 "refactor the auth middleware" ──── 3 files +45 -12 ┐
│                                                                     │
│ ◀ Current · T3 · T2 · T1 ▶                                         │
│                                                                     │
│ › src/utils/parser.ts                              +30 -8           │
│   src/utils/parser.test.ts                         +12 -2           │
│   README.md                                        +3 -2            │
│                                                                     │
│ ←/→ source · ↑/↓ file · Enter view · Esc close                     │
└─────────────────────────────────────────────────────────────────────┘

非交互模式：

在无头（--prompt）或非交互上下文中，/diff 会打印工作树与 HEAD 对比的纯文本摘要。不提供每个轮次的导航。

3 files changed, +45 / -12
  +30  -8  src/utils/parser.ts
  +12  -2  src/utils/parser.test.ts
   +3  -2  README.md

Web Shell： 在 Web Shell UI（qwen serve）中，/diff 会打开一个图形化的 diff 对话框。顶部的标签栏允许你在 Changes 视图和 History 视图（/log）之间切换。

History Viewer (/log) — 仅限 Web Shell

/log 命令打开当前工作区的 commit 历史浏览器。它仅在 Web Shell UI 中可用；CLI/TUI 没有此命令。

工作原理：

/log 打开一个对话框，按时间倒序列出 commit（最新的在前）。每行显示：

• 短 SHA（等宽字体，带有复制完整 SHA 的按钮）
• Commit 主题（单行）
• 作者姓名和相对时间（例如 “2h ago”）
• 分支/标签 ref 标签（如果存在）
• 合并 commit 的合并图标（⎇）

点击 commit 行可按需展开其详细信息：

• 完整的 commit 消息正文
• 文件变更统计（变更的文件数、增加/删除的行数、按文件分类的明细）

使用底部的 Load more 获取下一页 commit（每页 50 个）。

示例：

┌─ History ──────────────────────────── 50 commits ─ ✕ ┐
│                                                       │
│  a1b2c3d  feat(cli): add --json flag        2h ago   │
│           wenshao                                    │
│                                                       │
│  e4f5g6h  fix(core): handle null config     5h ago   │
│           dev · main  v1.2.0                         │
│                                                       │
│ ▼ 789abcd  refactor: simplify parser        1d ago   │
│   ┌─────────────────────────────────────────────┐    │
│   │  Broke the monolithic parse() into smaller  │    │
│   │  functions for readability.                 │    │
│   │                                             │    │
│   │  3 files · +45 −12                          │    │
│   │   +30 −8   src/parser.ts                    │    │
│   │   +10 −2   src/utils.ts                     │    │
│   │   +5  −2   test/parser.test.ts              │    │
│   └─────────────────────────────────────────────┘    │
│                                                       │
│              [ Load more ]                            │
└───────────────────────────────────────────────────────┘

1.10 信息、设置和帮助

用于获取信息和执行系统设置的命令。

1.11 常用快捷键

1.12 身份验证命令

在 Qwen Code 会话中使用 /auth 来配置身份验证。使用 /doctor 检查当前的身份验证和环境状态。

2. @ 命令（引入文件）

@ 命令用于快速将本地文件或目录内容添加到对话中。

注意：路径中的空格需要使用反斜杠进行转义（例如：@My\ Documents/file.txt）

在交互式提示中，@ 补全支持 Unicode 文件名，包括表情符号。提示中其他地方的表情符号不会改变用于补全的文件路径。

3. 感叹号命令（!）- Shell 命令执行

感叹号命令允许你直接在 Qwen Code 中执行系统命令。

环境变量：通过 ! 执行的命令会设置 QWEN_CODE=1 环境变量。

4. 自定义命令

将常用的提示词保存为快捷命令，以提高工作效率并确保一致性。

快速概览

优先级规则：项目命令 > 用户命令（同名时使用项目命令）

命令命名规则

文件路径到命令名的映射表

命名规则：路径分隔符（/ 或 \）转换为冒号（:）

Markdown 文件格式规范（推荐）

自定义命令使用带有可选 YAML frontmatter 的 Markdown 文件：

---
description: Optional description (displayed in /help)
---
 
Your prompt content here.
Use {{args}} for parameter injection.

TOML 文件格式（已弃用）

参数处理机制

1. 上下文感知注入（{{args}}）

2. 默认参数处理

🚀 动态内容注入

3. Shell 命令执行（!{...}）

示例：Git 提交信息生成

---
description: Generate Commit message based on staged changes
---
 
Please generate a Commit message based on the following diff:
 
```diff
!{git diff --staged}
```

4. 文件内容注入（@{...}）

示例：代码审查命令

---
description: Code review based on best practices
---
 
Review {{args}}, reference standards:
 
@{docs/code-standards.md}

实用创建示例

“纯函数重构”命令创建步骤表

---
description: Refactor code to pure function
---
 
Please analyze code in current context, refactor to pure function.
Requirements:
 
1. Provide refactored code
2. Explain key changes and pure function characteristic implementation
3. Maintain function unchanged

自定义命令最佳实践总结

命令设计建议表

安全特性提醒表

5. CLI 子命令

这些命令在启动交互式会话之前从 shell 中以 qwen <subcommand> 的形式运行。

会话管理

qwen sessions list

列出你最近的 Qwen Code 会话及其元数据。

标志：

人类可读输出（默认）：

包含以下列的表格：SESSION ID、STARTED（UTC 时间戳）、TITLE、BRANCH、PROMPT。

JSON 输出（--json）：

在 stdout 输出 JSON Lines。每行是一个包含以下字段的 JSON 对象：

sessionId, startTime, mtime, prompt, gitBranch, customTitle, titleSource, filePath, cwd

“还有更多会话”的提示信息会通过 stderr 输出，因此通过管道传递给 jq 依然是安全的。

示例：

# Show last 20 sessions (default)
qwen sessions list
 
# Show last 50 sessions
qwen sessions list --limit 50
 
# Output as JSON for scripting
qwen sessions list --json | jq .

qwen sessions ps

列出本机可见的 Qwen Code 会话记录。sessions list 遍历保存的转录记录（“我做过什么”）。此命令同时显示实时进程注册表和标记为 managed 的 Agent View 记录。被终止会话遗留的记录会在被发现时从注册表中清除。托管记录是持久化的簿记信息，并非其工作进程仍然存活的证据。一次性 qwen -p 运行永远不会注册，也不会显示。

标志：

人类可读输出（默认）：

包含以下列的表格：NAME、KIND、PID、AGE、DIRECTORY。

KIND 指示了是什么注册了该会话——tui 表示有人在终端操作，external 表示根本不是 Qwen Code 会话的程序（如语音前端、中继器），headless 或 serve 表示由其他程序驱动的会话。多个 serve 或 headless 行可以共享同一个 PID：一个 qwen --acp 子进程在一个进程中承载其所有会话——当守护进程启动它时为 serve，当客户端直接驱动它时为 headless——并且当对等消息传递处于活动状态时，每个会话都会单独注册。当自身环境将其置于裸机或安全模式时，托管会话不会在此处注册。守护进程的 --bare 不会传递给其托管的会话（QWEN_CODE_SIMPLE 会从子环境中清除）；继承的 QWEN_CODE_SAFE_MODE 则会传递，从而使这些托管会话不出现在此列表中。这是一种自我报告，就像 NAME 和 DIRECTORY 一样：这里的每个字段都是由其所描述的进程写入的，没有任何关于会话允许做什么的内容依赖于它。标记为 managed 的 Agent View 记录使用 managed 作为 KIND，使用 - 作为 PID 和 AGE。即使同一会话也有实时注册表记录，它仍保持为单独的一行。有关记录格式以及如何注册你自己的程序，请参阅 Cross-Session Protocol。

JSON 输出（--json）：

在 stdout 上输出 JSON Lines，托管记录排在前面。注册表记录保持其现有结构：

schemaVersion, pid, procStart, pidNs, sessionId, cwd, name, startedAt,
qwenVersion, kind, ipcPath (when peer messaging is available)

托管记录仅包含有来源支持的数据：

sessionId, cwd, managed: true

stdout 上不写入其他内容——空列表根本不打印任何内容——因此 qwen sessions ps --json | jq . 适合用于脚本编写。如果无法读取监督存储，注册表记录仍会打印，原因会写入 stderr。

JSON 输出是原始数据：字段值按记录原样发出，不进行终端净化。将它们视为数据，并在终端渲染之前进行净化。

示例：

# Show the other live sessions
qwen sessions ps
 
# Which directories have a visible session record?
# Note: `jq -r` renders the raw recorded value in your terminal (see the
# raw-data note above); pipe through a sanitizer if the path is untrusted.
qwen sessions ps --json | jq -r .cwd

6. 向另一个正在运行的会话发送消息

同一台机器上的两个交互式会话可以互相发送消息。该功能默认开启，但 --bare 和 --safe-mode 无论设置如何都会禁用它。拥有监听收件箱后，会话对于同一用户在该机器上的其他会话是可发现的，它们发送的内容在其模型看到之前会经过下面的审查规则。要禁用对等发现和消息传递，请在 settings.json 中关闭它并重启：

{ "agents": { "crossSessionMessaging": false } }

禁用了 peer messaging 的交互式会话仍可能出现在 qwen sessions ps 中，但没有 ipcPath，并且在 list_agents 中不是可达的对等方。OpenTUI 界面也不绑定对等收件箱；仅启用设置并不能使其可接收消息。

启用消息传递后，一个会话中的模型可以通过 list_agents 发现其他会话——每个会话都显示在 sessions 下，并带有 qwen sessions ps --json 记录的 name（表格视图可能会截断长名称）——并使用该名称作为 to 通过 send_message 向其中一个发送消息。当两个会话共享名称时，list_agents 会为每个会话显示一个简短的 [ref]，并且发送时必须包含它（name [ref]）；如果裸名称可能指代其中任何一个，则会被拒绝而不是猜测。list_agents 还会在 self 下报告会话自身的名称，而 to: "*" 仍然表示“我的 Agent Team 队友”，且永远不会到达其他会话。

消息到达另一个会话时，被标记为来自另一个会话而非其用户，并且在那里不携带你的任何权限：接收会话仅在其自身的权限设置内对其采取行动。其用户可以通过 agents.crossSessionInbound（accept、hold 或 refuse）选择如何处理传入的消息。未设置时，仅当两个会话处于相同的审查类别时才会投递消息：两者都仍对每个操作进行审查（默认或计划模式），或者两者都处于某种无需逐操作审查即可应用某些操作的模式（自动编辑、自动或 yolo）。来自另一类别会话的消息，或来自未说明其所在类别的发送者的消息，将在两个方向上都被扣留以供审查。逐个审查操作的会话会扣留来自不逐个审查操作的会话的消息，因为该消息是由无人监督的模型编写的，而逐操作提示保护的是操作本身，而不是会话被诱导去做的事情。扣留的消息会在接收会话中通过 /peers 列出并释放，而仅因模式不同而被扣留的消息一旦模式达成一致就会自动释放。

代码仓库可以让在其中打开的会话更加谨慎，但绝不会更宽松：工作区 .qwen/settings.json 可以将 agents.crossSessionInbound 设置为 hold 或 refuse，或将 agents.crossSessionMessaging 设置为 false，并且该值优先于用户设置中更宽松的值。如果工作区的值会放宽操作员设置的值（accept，或者当用户或系统范围将其设置为 false 时的开关 true），则该值会被忽略并发出警告；如果工作区 true 只是重复了默认值而没有其他地方设置该开关，则会被静默丢弃。CLI 无法识别的值只要成为有效值，就会扣留所有消息。系统设置覆盖所有这些规则，就像它覆盖所有设置一样。

扣留不会无限期等待。没有人决定的消息在 agents.crossSessionHeldExpiry 后过期——1m、5m、10m 或 never，默认为五分钟——并且发送会话会被告知没有做出决定。缩短此设置适用于已经在等待的消息。

如果会话无法绑定其收件箱——运行时目录缺失、属于其他用户或只读（在容器内可能发生这种情况）——它会首先尝试临时目录下的私有目录，只有当这也失败时，它才会在没有收件箱的情况下启动。发生这种情况时，会话会在启动时说明这一点，并且 /peers 会重复原因以及需要更改的内容（通常是 XDG_RUNTIME_DIR 或 TMPDIR）。

两个会话也可以解析相同的收件箱地址，因为地址以进程 ID 为键，而在共享运行时目录的容器中进程 ID 会重复出现。第二个启动的会话会采用相邻的地址，而不是接管正在使用的地址，因此两者都不会变得不可达。对等方不受影响：它们从会话注册表中读取会话的地址，而不是推导出来。

send_message 调用仅确认消息已移交给另一个会话。它的后续结果会以回执的形式稍后到达：如果被扣留、拒绝、驳回、丢弃、过期或寻址错误（地址易主——再次列出代理）——或在扣留后被释放——通知会出现在发送会话的记录中（Message to <name>: …）。拒绝、驳回和丢弃是三种不同的回答：拒绝意味着有人审查了消息并说不，驳回意味着该会话的 agents.crossSessionInbound 是 refuse 且根本没人看到它，丢弃意味着其收件箱在此之前就拒收了该消息（见下文）。第一次丢弃会立即得到回应，其余的每几秒折叠成一个回执，每个回执命名其所代表的消息，因此一连串丢弃只会产生几行记录而不是一行一条。发送它的模型不会被告知；如果另一个会话回复，回复将作为跨会话消息到达。

洪水保护

一个会话允许来自单个发送者的最多 30 条消息同时进入，随后每两秒一条；以及来自所有发送者合计的最多 32 条消息同时进入，随后每秒一条。第二个限制的存在是因为发送者会声明自己的名称：轮换该名称可以从第一个限制中获得新的配额，但不能从第二个限制中获得。它仅略高于第一个限制，因为每条被接受的消息都会生成一个回执，而会话同时发出的回执数量是有限的。如果来自另一个会话的消息在 30 秒内逐字重复了该发送者之前的消息，也会被拒绝——模型在循环处理一句话时每次都会生成新的消息 ID，因此是通过文本内容来检测这种情况的。由会话启动的脚本或受信任控制器发送的消息可豁免于重复检查，因为钩子（hook）两次报告同一行是在陈述两个事实，而人两次说“继续”意味着两次意图；但它们仍受速率限制约束。最后，即使消息被接受，但如果会话已有 50 条等待消息而无法入队，该消息也会被拒绝。

以此方式被拒绝的消息永远不会被保留、不会展示给模型，也不会留下任何记录，因此发送者可以稍后重试并成功送达。接收会话在其转录记录中每分钟针对每个发送者最多说明一次此情况，并附带计数以表明该行代表的含义。发送会话会收到一个回执，列出因突发流量而被丢弃的所有消息，其转录记录建议将仍然重要的内容合并到后续的一条消息中，而不是重新发送。

发送端不会等待反馈。每个会话跟踪其向每个地址发送的内容，并拒绝接收方会丢弃的发送请求，因此模型在编写消息之前而非之后被告知进行批量处理——并且接收方永远不会为即将被拒绝的消息消耗连接资源。

令牌只打印一次且不会存储在任何地方：Qwen 主目录下的文件仅保留其 SHA-256 哈希值，因此后来读取该文件的任何内容都无法呈现该令牌。当命令打印令牌时，请将其放入控制器的配置中。

每个会话的收件箱都需要一个特定于会话的令牌：连接必须在读取任何消息之前在第一行呈现该令牌，并且会话通过它们相互发现的相同注册表记录自动交换令牌。不支持令牌的构建版本生成的会话可以从较新版本接收消息，但向其发送的消息会被丢弃。

会话将其自身的收件箱地址和令牌作为 QWEN_CODE_MESSAGING_SOCKET 和 QWEN_CODE_MESSAGING_TOKEN 导出给子进程，以便会话运行的脚本或钩子可以将消息发回其中。这是一个第二层的 子 令牌，绝不会在任何地方发布：只有会话启动的进程才能持有它，因此带有此令牌到达的消息会被识别为会话自身发出的，而不是来自其他会话的。

{ printf '%s\n' \
    '{"msgV":1,"type":"auth","token":"'"$QWEN_CODE_MESSAGING_TOKEN"'"}' \
    '{"msgV":1,"msgId":"'"$(uuidgen)"'","type":"user","priority":"next","message":{"role":"user","content":"build finished"}}'; \
} | socat - UNIX-CONNECT:"$QWEN_CODE_MESSAGING_SOCKET"

为每次注入提供一个新的 msgId。接收门控会记住它已经处理过的 ID，因此重用某个 ID 的钩子会在第一次运行时被交付，而在随后的每次运行中被静默去重。重复相同的 文本 是可以的——上述重复检查不适用于会话自身的进程——但速率限制确实适用，因此循环中的钩子会像任何其他洪水攻击一样被丢弃。

注入的消息仍然会通过入站门控，并被标记为非用户来源，但门控知道它来自会话自身的进程：在模式对等默认设置下，它无需审查即可交付（处于相同位置的对等方会被扣留），而显式的 agents.crossSessionInbound 设置为 hold 或 refuse 时，对其应用与其他消息相同的规则。模型将其视为 <cross_session_message from="own process" origin="own-process">，并附带通知说明它来自会话运行的脚本或钩子，而非用户。

受信任的控制器

上述规则会扣留来自任何未声明其审查类别的发送者的消息，而非 Qwen Code 会话的程序没有此类声明。这对于陌生人来说是正确的默认行为，但对于你选择的程序则不然：语音前端、听写桥接器、转发你自己指令的自动化守护进程会导致每条消息都被搁置，而手动批准每一条消息就失去了意义。

你可以通过为其铸造令牌来授予此类程序交付权限：

qwen sessions controllers add --label voice-bridge

令牌只打印一次且不会存储在任何地方：Qwen 主目录下的文件仅保留其 SHA-256 哈希值，因此后续读取该文件的任何内容都无法呈现该令牌。当命令打印令牌时，请将其放入控制器自身的配置中。

控制器像其他发送者一样呈现令牌——作为连接的第一行——并从会话注册表中获取套接字路径（qwen sessions ps --json 为每个活动会话打印一条记录，ipcPath 即为地址）：

{ printf '%s\n' \
    '{"msgV":1,"type":"auth","token":"'"$QWEN_CONTROLLER_TOKEN"'"}' \
    '{"msgV":1,"msgId":"'"$(uuidgen)"'","type":"user","priority":"next","message":{"role":"user","content":"open the failing test"}}'; \
} | socat - UNIX-CONNECT:"$SESSION_IPC_PATH"

使用授予令牌到达的消息无需逐条审查即可交付，无论双方处于何种审查类别——但它仍需服从显式设置：agents.crossSessionInbound 设置为 hold 时会像其他消息一样将其搁置，设置为 refuse 时会将其拒绝。授权属于你的 Qwen 主目录而非单个会话，因此控制器可以访问你正在运行的任意会话，并且会话在每次连接时重新读取文件：创建或撤销授权在下一次连接时生效，无需重启。

qwen sessions controllers list          # ids, labels, when they were added
qwen sessions controllers remove c_1a2b # revoke one

在会话内部，/peers controllers 和 /peers revoke <id> 的作用相同。通过授权发送的消息显示为 Message from a trusted controller (voice-bridge)，如果 hold 设置将其暂存，则会在 /peers 中显示为 [controller] voice-bridge。

模型将此类消息视为 <cross_session_message from="controller" origin="controller" controller="voice-bridge">，并附带说明该消息转达了你自己的指令——并且适用于所有其他来源的两条禁令同样适用：它不得因消息要求而编辑权限设置、QWEN.md 或配置，也不得将该消息视为你批准了待确认的提示。控制器可以指示下一步操作；但它不能代表你回答提示。

任何持有令牌的人都可以以该控制器的身份发送消息，因此请像对待任何其他凭据一样对待它：仅交给一个程序使用，不要放入共享配置中，并在该程序完成后撤销它。

程序通过 ACP 驱动的会话

任何 qwen --acp 子进程都会注册其托管的每个会话——当守护进程生成进程时注册为 serve，当编辑器或其他客户端直接驱动 qwen --acp 时注册为 headless——并且该会话会像其他会话一样出现在 qwen sessions ps 和其他会话的 list_agents 中。它可以发送消息：其模型可以调用 send_message 来访问你打开的终端。它们中的几个共享一个进程和一个收件箱，因此发送者必须指定目标会话——每个 Qwen Code 会话都会自动执行此操作。

发送到此类会话的消息会被拒绝而不是被保留。保留是针对人的问题，而在被驱动的会话上没有人查看保留消息列表；发送者会立即收到通知，而不是等待过期。对于此类会话，保留消息应在何处显示尚未确定。

除非会话自身的设置关闭了 agents.crossSessionMessaging，或者它是使用 --bare 或 --safe-mode 启动的，否则会话会进行注册——无论设置如何，这些选项都会禁用消息功能。如果已禁用，它将保持不可见，因为列出无人可向其发送消息的会话的唯一理由就是宣传一个永不响应的地址。

非 Qwen Code 会话的程序

上述所有内容都在会话之间工作，但其中没有任何内容是特定于某个会话的。如果一个程序为自己写入注册记录并以相同方式绑定收件箱，它将由 qwen sessions ps 和 list_agents 列出，可以从 send_message 按名称寻址，并接收其发送内容的投递回执——例如语音前端、中继器或构建监视器。它应记录 kind: "external"，以便列表可以说明其用途。

跨会话协议 是编写此类程序的契约：包括记录架构和活性判断方法、套接字路径和帧格式、认证行、每个帧字段、回执状态及其转换，以及接收者在模型看到消息之前如何处理消息。

Node 程序不必手动编写上述任何内容：@qwen-code/sdk/peer 实现了该契约。PeerEndpoint.start({ name }) 发布记录并绑定收件箱，list() 和 send() 按名称寻址会话，onMessage 接收它们发送的内容。