명령어

이 문서는 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 내장 Skill

이 명령어들은 특수한 워크플로우를 제공하는 번들 skill을 호출합니다.

자세한 /review 문서는 코드 리뷰를 참조하세요.

1.6 사이드 질문 (/btw)

/btw 명령어를 사용하면 기본 대화 흐름을 중단하거나 영향을 주지 않고 빠른 사이드 질문을 할 수 있습니다.

작동 방식:

• 사이드 질문은 최근 대화 컨텍스트(최대 20개 메시지까지)와 함께 별도의 API 호출로 전송됩니다
• 응답은 Composer 위에 표시됩니다 — 대기 중에도 계속 입력할 수 있습니다
• 기본 대화가 차단되지 않습니다 — 독립적으로 계속 진행됩니다
• 사이드 질문 응답은 기본 대화 기록에 포함되지 않습니다
• 답변은 전체 Markdown 지원과 함께 렌더링됩니다 (코드 블록, 목록, 표 등)

키보드 단축키 (대화형 모드):

예시:

(기본 대화가 코드 리팩터링에 관한 동안)

> /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는 활성 상태 — 계속 입력 가능)

(답변이 도착한 후)

  ╭──────────────────────────────────────────╮
  │ /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 여전히 활성 상태)

지원되는 실행 모드:

1.7 두 번째 의견 (/advisor)

/advisor 명령어는 지금까지의 대화에 대한 독립적이고 읽기 전용 리뷰를 실행하여 구조화된 두 번째 의견을 반환합니다 — 작업을 수행하거나 기본 대화를 중단하지 않습니다.

작동 방식:

• 리뷰는 최근 대화 컨텍스트(최대 최근 40개 메시지)와 함께 별도의 단일 턴 API 호출로 전송됩니다
• 리뷰어 모델은 도구를 실행할 수 없습니다 — 도구는 요청 수준에서 제거되며(/btw와 동일한 메커니즘), 리뷰는 코드를 작성하거나 명령을 실행하지 않습니다; 모든 주장은 보이는 트랜스크립트에 기반해야 합니다
• 기본 대화는 중단되지 않습니다; 리뷰는 사용자에게만 표시됩니다
• 리뷰는 /advisor · <model> 헤더 아래에 네 개의 고정 섹션 — Verdict, Risks, Missing evidence, Recommendation — 이 있는 박스형 마크다운 블록으로 렌더링되며, 해결된 리뷰어 모델 이름을 표시합니다
• fire-and-forget 방식이라 세션을 사용할 수 있게 두는 /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, 파일을 수정한 각 모델 턴마다 하나의 탭. 가장 최근 턴이 먼저 표시됩니다. 각 탭에는 컨텍스트를 위한 원본 프롬프트의 미리보기가 표시됩니다.

파일 목록은 파일별 통계(추가/삭제된 줄 수)와 특수 상태에 대한 태그(new, deleted, untracked, binary, truncated, oversized)를 표시합니다. 파일에서 Enter를 누르면 구문 강조된 hunk와 함께 인라인 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 뷰어 (/log) — Web Shell 전용

/log 명령어는 현재 작업 공간의 커밋 기록 브라우저를 엽니다. Web Shell UI에서만 사용할 수 있으며, CLI/TUI에는 이 명령어가 없습니다.

작동 방식:

/log는 커밋을 역순(최신 우선)으로 나열하는 대화 상자를 엽니다. 각 행에는 다음이 표시됩니다:

• 짧은 SHA (모노스페이스, 전체 SHA를 위한 복사 버튼 포함)
• 커밋 제목 (한 줄)
• 작성자 이름과 상대적 시간 (예: “2h ago”)
• 브랜치/태그 ref 라벨 (있는 경우)
• 병합 커밋에 대한 병합 아이콘 (⎇)

커밋 행을 클릭하면 상세 정보가 필요에 따라 확장됩니다:

• 전체 커밋 메시지 본문
• 파일 변경 통계 (변경된 파일, 추가/삭제된 줄, 파일별 세부 정보)

하단의 Load more를 사용하여 다음 페이지의 커밋을 가져옵니다 (페이지당 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)

3. 느낌표 명령어 (!) - Shell 명령어 실행

느낌표 명령어를 사용하면 Qwen Code 내에서 시스템 명령어를 직접 실행할 수 있습니다.

환경 변수: !를 통해 실행된 명령어는 QWEN_CODE=1 환경 변수를 설정합니다.

4. 사용자 정의 명령어

자주 사용하는 프롬프트를 단축 명령어로 저장하여 작업 효율을 높이고 일관성을 유지하세요.

빠른 개요

우선순위 규칙: 프로젝트 명령어 > 사용자 명령어 (이름이 같을 때 프로젝트 명령어가 사용됨)

명령어 명명 규칙

파일 경로 → 명령어 이름 매핑 표

명명 규칙: 경로 구분자(/ 또는 \)가 콜론(:)으로 변환됩니다

Markdown 파일 형식 사양 (권장)

사용자 정의 명령어는 선택적 YAML 프론트매터가 있는 Markdown 파일을 사용합니다:

---
description: 선택적 설명 (/help에 표시됨)
---
 
여기에 프롬프트 내용을 작성하세요.
매개변수 주입에 {{args}}를 사용하세요.

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 서브명령어

이 명령어들은 대화형 세션을 시작하기 전에 셸에서 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로 파이프해도 안전합니다.

예시:

# 최근 20개 세션 표시 (기본값)
qwen sessions list
 
# 최근 50개 세션 표시
qwen sessions list --limit 50
 
# 스크립팅을 위해 JSON으로 출력
qwen sessions list --json | jq .

qwen sessions ps

현재 이 기계에 등록된 Qwen Code 세션을 나열합니다. sessions list는 저장된 트랜스크립트를 탐색하는 반면(“무엇을 작업했는가”), 이것은 라이브 프로세스 레지스트리를 탐색합니다(“지금 무엇이 실행 중인가”). 종료된 세션이 남긴 기록은 발견될 때 정리됩니다. 일회성 qwen -p 실행은 등록되지 않으므로 표시되지 않습니다.

플래그:

사람이 읽을 수 있는 출력 (기본값):

다음 열이 있는 표: NAME, KIND, PID, AGE, DIRECTORY.

KIND는 세션을 등록한 주체를 나타냅니다 — 터미널 사용자는 tui, Qwen Code 세션이 아닌 프로그램(음성 프론트엔드, 릴레이)은 external, 다른 프로그램이 구동하는 세션은 headless 또는 serve입니다. 여러 serve 또는 headless 행이 하나의 PID를 공유할 수 있습니다: qwen --acp 자식은 하나의 프로세스에서 모든 세션을 호스팅하며 — 데몬이 생성한 경우 serve, 클라이언트가 직접 구동하는 경우 headless — 각각 별도로 등록됩니다. 이는 NAME, DIRECTORY와 마찬가지로 자기 보고입니다: 여기 있는 모든 필드는 해당 세션 프로세스가 직접 작성한 것이며, 세션이 수행할 수 있는 작업은 이에 의존하지 않습니다. 레코드 형식과 자체 프로그램 등록 방법은 Cross-Session Protocol을 참조하세요.

JSON 출력 (--json):

stdout에 JSON Lines를 최신 세션부터 출력합니다. 각 줄은 다음 필드를 가진 JSON 객체입니다:

schemaVersion, pid, procStart, pidNs, sessionId, cwd, name, startedAt,
qwenVersion, kind, ipcPath (피어 메시징 사용 가능한 경우)

stdout에는 다른 것이 출력되지 않습니다 — 빈 목록은 아무것도 출력하지 않으므로 qwen sessions ps --json | jq .는 안전하게 스크립팅할 수 있습니다.

JSON 출력은 원시 데이터입니다: 필드 값은 기록된 그대로 출력되며, 터미널 sanitization이 없습니다. 데이터로 취급하고 터미널에 렌더링하기 전에 sanitization하세요.

예시:

# 다른 라이브 세션 표시
qwen sessions ps
 
# 어떤 디렉토리가 현재 사용 중인가?
# 참고: `jq -r`은 기록된 원시 값을 터미널에 렌더링합니다(위의 원시 데이터
# 노트 참조); 경로가 신뢰할 수 없으면 sanitizer를 통해 파이프하세요.
qwen sessions ps --json | jq -r .cwd

6. 다른 실행 중인 세션에 메시지 보내기

같은 머신의 두 대화형 세션은 서로 메시지를 보낼 수 있습니다. 이 기능은 실험적이며 기본적으로 꺼져 있습니다; settings.json에서 켜고 재시작하세요:

{ "agents": { "crossSessionMessaging": true } }

활성화하면, 한 세션의 모델이 list_agents로 다른 세션을 발견할 수 있습니다 — 각 세션은 sessions 아래에 qwen sessions ps --json이 기록하는 name으로 표시됩니다(표 뷰에서는 긴 이름이 잘릴 수 있음) — send_message로 해당 이름을 to로 사용하여 메시지를 보냅니다. 두 세션이 같은 이름을 공유할 때, list_agents는 각 세션에 짧은 [ref]를 표시하며 전송 시 이를 포함해야 합니다(name [ref]); 둘 중 하나일 수 있는 단순 이름은 추측하지 않고 거부됩니다. list_agents는 세션 자체의 이름도 self 아래에 보고하며, to: "*"는 여전히 “내 Agent Team 팀원”을 의미하고 다른 세션에는 전달되지 않습니다.

메시지는 다른 세션에서 다른 세션으로부터 온 것으로 표시되어 도착하며, 해당 세션의 사용자로부터 온 것이 아니고 그곳에서 어떠한 권한도 가지지 않습니다: 수신 세션은 자체 권한 설정 내에서만 메시지에 따라 행동합니다. 사용자는 agents.crossSessionInbound(accept, hold, 또는 refuse)로 수신 메시지의 처리 방식을 선택할 수 있습니다. 설정되지 않은 경우, 두 세션이 같은 검토 클래스에 있을 때만 메시지가 전달됩니다: 양쪽 모두 각 작업을 검토하는 모드(기본 또는 계획 모드)이거나, 양쪽 모두 작업별 검토 없이 일부 작업을 적용하는 모드(auto-edit, auto, 또는 yolo)인 경우입니다. 다른 클래스의 세션에서 온 메시지나 어느 클래스에 속하는지 밝히지 않은 발신자의 메시지는 검토를 위해 보류됩니다 — 양방향 모두 마찬가지입니다. 각 작업을 검토하는 세션은 그렇지 않은 세션의 메시지를 보류합니다. 해당 메시지가 아무도 감시하지 않는 모델이 작성한 것이기 때문이며, 작업별 프롬프트는 작업 자체를 보호하지 세션이 설득당하는 내용을 보호하지 않습니다. 보류된 메시지는 수신 세션에서 /peers로 목록을 확인하고 해제할 수 있으며, 모드 차이로만 보류된 메시지는 두 세션이 동의하게 되면 자동으로 해제됩니다.

저장소는 그곳에서 열린 세션을 더 엄격하게 만들 수 있지만, 더 느슨하게는 만들 수 없습니다: 워크스페이스 .qwen/settings.json에서 agents.crossSessionInbound를 hold 또는 refuse로 설정하거나 agents.crossSessionMessaging을 false로 설정할 수 있으며, 이 값은 사용자 설정의 더 느슨한 값보다 우선합니다. 설정을 느슨하게 만드는 워크스페이스 값(accept 또는 스위치의 true)은 경고와 함께 무시되며, CLI가 인식하지 못하는 값은 유효값일 때마다 모든 메시지를 보류합니다. 시스템 설정은 다른 모든 설정과 마찬가지로 이보다 우선합니다.

보류는 무기한 기다리지 않습니다. 아무도 결정하지 않는 메시지는 agents.crossSessionHeldExpiry — 1m, 5m, 10m, 또는 never(기본값 5분) — 이후에 만료되며, 보내는 세션에게 결정이 없었음이 통보됩니다. 설정을 줄이면 이미 대기 중인 메시지에도 적용됩니다.

세션이 inbox를 바인딩할 수 없는 경우 — 런타임 디렉토리가 없거나, 다른 사용자가 소유하거나, 컨테이너 내부에서처럼 읽기 전용인 경우 — 먼저 임시 디렉토리 아래의 비공개 디렉토리를 시도하고, 그것도 실패한 경우에만 inbox 없이 시작합니다. 이 경우 세션은 시작 시 이를 알리며, /peers는 원인과 변경 방법을 반복합니다(보통 XDG_RUNTIME_DIR 또는 TMPDIR).

두 세션이 같은 inbox 주소를 해석할 수도 있습니다. 주소가 프로세스 ID로 키잉되고, 프로세스 ID는 런타임 디렉토리를 공유하는 컨테이너 간에 반복되기 때문입니다. 나중에 시작하는 세션은 사용 중인 주소를 가져가는 대신 인접한 주소를 사용하므로 어느 쪽도 도달 불가능해지지 않습니다. 피어는 영향을 받지 않습니다: 세션의 주소를 세션 레지스트리에서 읽으며 직접 유도하지 않습니다.

send_message 호출은 메시지가 다른 세션에 전달된 것만 확인합니다. 그 결과는 나중에 영수증으로 도착합니다: 보류, 거부, 거절, 드롭, 만료, 잘못된 주소(주소가 변경된 경우 — 에이전트를 다시 나열하세요), 또는 보류 후 해제된 경우 — 보내는 세션의 트랜스크립트에 알림이 표시됩니다(Message to <name>: …). 거부(declined), 거절(refused), 드롭(dropped)은 세 가지 다른 응답입니다: 거부는 누군가 메시지를 검토하고 거부한 것을 의미하고, 거절은 해당 세션의 agents.crossSessionInbound가 refuse라 아무도 보지 못한 것을 의미하며, 드롭은 inbox가 그 전에 메시지를 돌려보낸 것을 의미합니다(아래 참조). 첫 번째 드롭은 즉시 응답하고, 나머지는 몇 초마다의 영수증에 통합되며, 각각이 대표하는 메시지의 이름을 포함하므로, 연속 드롭도 한 줄씩 대신 몇 줄로 표시됩니다. 보낸 모델에게는 알려지지 않으며, 다른 세션이 응답하면 해당 응답은 교차 세션 메시지로 도착합니다.

플러드 보호

세션은 한 발신자에게서 한 번에 최대 30개의 메시지를 수용한 후 2초에 하나씩 수용하며, 모든 발신자를 합쳐 한 번에 최대 32개까지 수용한 후 1초에 하나씩 수용합니다. 두 번째 제한이 있는 이유는 발신자가 자신의 이름을 밝히기 때문입니다: 이름을 순환시키면 첫 번째 제한의 새 할당량을 얻지만 두 번째 제한에서는 얻지 못합니다. 두 번째 제한이 첫 번째보다 간신히 높은 이유는, 수용된 메시지마다 영수증이 발행되며 세션이 한 번에 보낼 수 있는 영수증 수에 한계가 있기 때문입니다. 다른 세션의 메시지가 30초 내에 해당 발신자의 이전 메시지를 단어 그대로 반복하면 역시 돌려보냅니다 — 한 문장을 반복하는 모델은 매번 새 메시지 ID를 생성하므로, 텍스트가 이를 잡아냅니다. 세션이 시작한 스크립트와 신뢰되는 컨트롤러의 메시지는 반복 검사에서 면제됩니다. hook이 같은 라인을 두 번 보고하는 것은 두 가지 사실을 보고하는 것이며, 사람이 “continue”를 두 번 말하는 것은 두 번 의미하기 때문입니다; 둘 다 속도 제한은 여전히 적용됩니다. 마지막으로, 수용되었지만 세션에 이미 50개가 대기 중이라 큐에 넣을 수 없는 메시지도 돌려보냅니다.

이 방식으로 돌려보낸 메시지는 보류되지 않고, 모델에 표시되지 않으며, 기록에 남지 않습니다. 따라서 발신자는 나중에 다시 시도하여 도달할 수 있습니다. 수신 세션은 트랜스크립트에 발신자당 1분에 한 번까지 이를 알리며, 해당 라인이 대표하는 메시지의 수를 포함합니다. 보내는 세션은 버스트로 소모된 모든 메시지를 이름으로 포함하는 영수증 하나를 받으며, 트랜스크립트는 재전송 대신 중요한 내용을 나중에 하나의 메시지로 통합하라고 안내합니다.

보내는 쪽은 결과를 기다리지 않습니다. 각 세션은 각 주소로 보낸 내용을 추적하고, 수신자가 드롭할 전송을 거부합니다. 따라서 모델은 메시지가 작성되기 전에 배칭하라는 안내를 받으며, 작성 후에는 아닙니다 — 수신자는 돌려보낼 메시지에 연결을 소비하지 않습니다.

Inbox 인증 및 스크립트 주입

각 세션의 inbox는 세션별 토큰을 요구합니다: 연결은 첫 번째 줄에 토큰을 제시해야 메시지를 읽을 수 있으며, 세션은 서로를 발견하는 데 사용하는 같은 레지스트리 레코드를 통해 토큰을 자동으로 교환합니다. 토큰 지원이 없는 빌드의 세션은 새 빌드에서 메시지를 받을 수 있지만, 새 빌드로의 전송은 드롭됩니다.

세션은 자신의 inbox 주소와 토큰을 QWEN_CODE_MESSAGING_SOCKET 및 QWEN_CODE_MESSAGING_TOKEN으로 자식 프로세스에 내보내므로, 세션이 실행하는 스크립트나 hook이 세션으로 메시지를 다시 보낼 수 있습니다. 이것은 어디에도 게시되지 않는 두 번째 자식 토큰입니다: 세션이 시작한 프로세스만 이를 보유할 수 있으므로, 이 토큰과 함께 도착하는 메시지는 다른 세션이 아닌 세션 자체의 메시지로 인식됩니다.

{ 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를 재사용하는 hook은 첫 번째에만 전달되고 이후 실행에서는 자동으로 중복 제거됩니다. 같은 _텍스트_를 반복하는 것은 괜찮습니다 — 위의 반복 검사는 세션 자체 프로세스에는 적용되지 않습니다 — 하지만 속도 제한은 적용되므로, 루프의 hook은 다른 플러드와 마찬가지로 드롭됩니다.

주입된 메시지는 여전히 인바운드 게이트를 통과하며 사용자로부터 온 것이 아닌 것으로 표시되지만, 게이트는 세션 자체 프로세스에서 온 것을 알고 있습니다: 모드 일치 기본값에서는 검토 없이 전달되며(같은 위치의 피어는 보류될 것입니다), 명시적인 agents.crossSessionInbound의 hold 또는 refuse는 다른 것과 마찬가지로 적용됩니다. 모델은 이를 <cross_session_message from="own process" origin="own-process">로 보며, 세션이 실행한 스크립트나 hook에서 온 것이지 사용자로부터 온 것이 아니라는 알림이 포함됩니다.

신뢰되는 컨트롤러

위 규칙은 어느 검토 클래스에 속하는지 밝히지 않는 발신자의 메시지를 보류하며, 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          # id, 라벨, 추가된 시점
qwen sessions controllers remove c_1a2b # 하나 철회

/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를 호출하여 열어둔 터미널에 도달할 수 있습니다. 여러 세션이 하나의 프로세스와 하나의 inbox를 공유하므로, 발신자는 의도하는 세션의 이름을 지정해야 합니다 — 모든 Qwen Code 세션이 자동으로 수행하는 방식입니다.

하나로 보내는 메시지는 보류 대신 거절됩니다. 보류는 사람에게 묻는 질문이며, 구동되는 세션을 대신해 보류된 메시지 목록을 감시하는 사람은 없습니다. 따라서 발신자는 만료를 기다리지 않고 즉시 통보를 받습니다. 보류된 메시지가 해당 세션에서 어떻게 표면으로 올라와야 하는지는 아직 정해지지 않았습니다.

세션은 자체 설정에 agents.crossSessionMessaging이 켜져 있는 동안에만 등록됩니다. 이 설정이 꺼져 있으면 보이지 않습니다. 아무도 메시지를 보낼 수 없는 세션을 나열하는 유일한 이유는 응답하지 않는 주소를 광고하는 것뿐이기 때문입니다.

Qwen Code 세션이 아닌 프로그램

위의 모든 것은 세션 간에 작동하지만, 그 중 어느 것도 특정 세션에 국한되지 않습니다. 자신을 위한 레지스트리 레코드를 작성하고 같은 방식으로 inbox를 바인딩하는 프로그램은 qwen sessions ps와 list_agents에 나열되며, send_message에서 이름으로 주소 지정할 수 있고, 보낸 것에 대한 전달 영수증을 받습니다 — 음성 프론트엔드, 릴레이, 빌드 감시자 등. kind: "external"를 기록해야 목록에서 이것이 무엇인지 나타낼 수 있습니다.

Cross-Session Protocol은 이를 작성하기 위한 계약입니다: 레코드 스키마와 활성 상태 판단 방법, 소켓 경로와 프레이밍, 인증 줄, 모든 프레임 필드, 영수증 상태와 전환, 그리고 수신자가 모델이 보기 전에 메시지에 대해 수행하는 작업을 정의합니다.

Node 프로그램은 이 중 어느 것도 수작업으로 작성할 필요가 없습니다: @qwen-code/sdk/peer가 계약을 구현합니다. PeerEndpoint.start({ name })은 레코드를 게시하고 inbox를 바인딩하며, list()와 send()는 이름으로 세션을 주소 지정하고, onMessage는 그들이 보내는 것을 수신합니다.