Comandos

Este documento detalha todos os comandos suportados pelo Qwen Code, ajudando você a gerenciar sessões, personalizar a interface e controlar seu comportamento de forma eficiente.

Os comandos do Qwen Code são acionados por meio de prefixos específicos e se dividem em três categorias:

1. Comandos Slash (/)

Os comandos slash são usados para gerenciar sessões, interface e comportamento básico do Qwen Code.

1.1 Gerenciamento de Sessões e Projetos

Esses comandos ajudam você a salvar, restaurar e resumir o progresso do trabalho.

1.2 Controle de Interface e Workspace

Comandos para ajustar a aparência da interface e o ambiente de trabalho.

1.3 Configurações de Idioma

Comandos específicos para controlar o idioma da interface e da saída.

• Idiomas de interface integrados disponíveis: zh-CN (Chinês Simplificado), en-US (Inglês), ru-RU (Russo), de-DE (Alemão), ja-JP (Japonês), pt-BR (Português - Brasil), fr-FR (Francês), ca-ES (Catalão)
• Exemplos de idioma de saída: Chinese, English, Japanese, etc.

1.4 Gerenciamento de Ferramentas e Modelos

Comandos para gerenciar ferramentas e modelos de IA.

1.5 Skills Integradas

Estes comandos invocam skills integradas que fornecem fluxos de trabalho especializados.

Consulte Code Review para a documentação completa do /review.

1.6 Pergunta Paralela (/btw)

O comando /btw permite que você faça perguntas paralelas rápidas sem interromper ou afetar o fluxo da conversa principal.

Como Funciona:

• A pergunta paralela é enviada como uma chamada de API separada com o contexto recente da conversa (até as últimas 20 mensagens)
• A resposta é exibida acima do Composer — você pode continuar digitando enquanto aguarda
• A conversa principal não é bloqueada — ela continua independentemente
• A resposta da pergunta paralela não faz parte do histórico da conversa principal
• As respostas são renderizadas com suporte completo a Markdown (blocos de código, listas, tabelas, etc.)

Atalhos de Teclado (Modo Interativo):

Exemplo:

(Enquanto a conversa principal é sobre refatorar código)

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

  ╭──────────────────────────────────────────╮
  │ /btw What's the difference between let   │
  │     and var in JavaScript?               │
  │                                          │
  │ + Respondendo...                         │
  │ Pressione Escape, Ctrl+C ou Ctrl+D para  │
  │ cancelar                                 │
  ╰──────────────────────────────────────────╯
  > (O Composer permanece ativo — continue digitando)

(Depois que a resposta chegar)

  ╭──────────────────────────────────────────╮
  │ /btw What's the difference between let   │
  │     and var in JavaScript?               │
  │                                          │
  │ `let` tem escopo de bloco, enquanto      │
  │ `var` tem escopo de função. `let` foi    │
  │ introduzido no ES6 e não faz hoist da    │
  │ mesma forma.                             │
  │                                          │
  │ Pressione Space, Enter ou Escape para    │
  │ dispensar                                │
  ╰──────────────────────────────────────────╯
  > (Composer ainda ativo)

Modos de Execução Suportados:

1.7 Segunda Opinião (/advisor)

O comando /advisor executa uma revisão independente e somente leitura da conversa até o momento e retorna uma segunda opinião estruturada — sem realizar a tarefa nem interromper a conversa principal.

Como Funciona:

• A revisão é enviada como uma chamada de API separada e de turno único com o contexto recente da conversa (até as últimas 40 mensagens)
• O modelo revisor não pode executar ferramentas — as ferramentas são removidas no nível da requisição (o mesmo mecanismo que o /btw), então a revisão nunca escreve código nem executa comandos; cada afirmação deve estar fundamentada na transcrição visível
• A conversa principal não é interrompida; a revisão é mostrada apenas para você
• A revisão é renderizada como um bloco markdown em caixa com quatro seções fixas — Veredito, Riscos, Evidência faltando e Recomendação — sob um cabeçalho /advisor · <model> que nomeia o modelo revisor resolvido
• Diferente do /btw, que é fire-and-forget e deixa a sessão utilizável, o /advisor bloqueia a entrada até a revisão retornar; em uma janela de contexto completa com um revisor forte, isso pode levar dezenas de segundos
• Por padrão, o modelo principal é usado; defina advisorModel para direcionar a revisão para um modelo diferente (tipicamente mais forte) — a transcrição recente é enviada para esse modelo mesmo quando ele usa outro provedor

Exemplo:

> /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.                                      │
  ╰──────────────────────────────────────────────────────╯

A revisão é renderizada em uma caixa com borda cujo cabeçalho nomeia o modelo revisor resolvido. Um advisorModel desconhecido não é validado antecipadamente — se o provedor o rejeitar, o /advisor reporta a falha, então verifique o nome do modelo; apenas seletores de alias não resolvíveis (ex.: fast sem modelo rápido configurado) retornam ao modelo principal. Requisições de advisor não usam fallbacks de modelo configurados.

Modos de Execução Suportados:

1.8 Resumo da Sessão (/recap)

O comando /recap gera um breve resumo de “onde você parou” da sessão atual, permitindo que você retome uma conversa antiga sem precisar rolar por páginas de histórico.

Como funciona:

• Usa o modelo rápido configurado (configuração fastModel) quando disponível, voltando para o modelo principal da sessão como fallback. Um modelo pequeno e barato é suficiente para um resumo.
• A conversa recente (até 30 mensagens, apenas texto — chamadas de ferramentas e respostas de ferramentas são filtradas) é enviada ao modelo com um system prompt restrito.
• O resumo é renderizado em cor esmaecida com o prefixo ❯ para se destacar das respostas reais do assistente.
• Recusa com um erro inline se um turno do modelo estiver em andamento ou outro comando estiver sendo processado. Se não houver conversa utilizável, ou se a geração subjacente falhar, o /recap mostra uma mensagem informativa curta em vez de um resumo — o comando manual sempre responde com algo.

Acionamento automático ao retornar de uma ausência:

Se o terminal ficar desfocado por 5+ minutos e for focado novamente, um resumo é gerado e exibido automaticamente (apenas quando nenhuma resposta do modelo estiver em progresso; caso contrário, ele aguarda o turno atual terminar e então é acionado). Diferente do comando manual, o acionamento automático é totalmente silencioso em caso de falha: se houver erros de geração ou não houver nada para resumir, nenhuma mensagem é adicionada ao histórico. Controlado pela configuração general.showSessionRecap (padrão: false); o comando manual /recap sempre funciona independentemente desta configuração.

Exemplo:

> /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 Visualizador de Diff (/diff)

O comando /diff abre um visualizador de diff interativo mostrando alterações não commitadas e diffs por turno. Use ←/→ para alternar entre o git diff atual e os turnos individuais da conversa, ↑/↓ para navegar pelos arquivos e Enter para visualizar os diffs inline.

Como funciona:

No modo interativo, o /diff abre um diálogo com um seletor de origem na parte superior:

• Current — working tree vs HEAD (git diff HEAD). Mostra todas as alterações não commitadas, incluindo arquivos staged, unstaged e untracked.
• T1, T2, T3, … — diffs por turno, uma aba por turno do modelo que modificou arquivos. Os turnos mais recentes aparecem primeiro. Cada aba mostra uma prévia do prompt original para contexto.

A lista de arquivos exibe estatísticas por arquivo (linhas adicionadas/removidas) com tags para estados especiais (new, deleted, untracked, binary, truncated, oversized). Pressione Enter em um arquivo para ver seu diff inline com hunks destacados por sintaxe.

Diffs por turno requerem que o file checkpointing esteja habilitado (ativado por padrão no modo interativo). Quando o file checkpointing está desativado, apenas a origem “Current” está disponível.

Atalhos de teclado:

Exemplo:

┌ /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                     │
└─────────────────────────────────────────────────────────────────────┘

Modo não interativo:

Em contextos headless (--prompt) ou não interativos, o /diff imprime um resumo em texto simples do working tree vs HEAD. A navegação por turno não está disponível.

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

Web Shell: Na UI do Web Shell (qwen serve), o /diff abre uma caixa de diálogo gráfica de diff. Uma barra de abas na parte superior permite alternar entre a visualização Changes e a visualização History (/log).

Visualizador de Histórico (/log) — Apenas Web Shell

O comando /log abre um navegador de histórico de commits para o workspace atual. Está disponível apenas na UI do Web Shell; a CLI/TUI não possui este comando.

Como funciona:

O /log abre uma caixa de diálogo listando commits em ordem cronológica inversa (mais recentes primeiro). Cada linha mostra:

• SHA curto (monoespaçado, com botão de cópia para o SHA completo)
• Assunto do commit (linha única)
• Nome do autor e tempo relativo (ex.: “2h ago”)
• Rótulos de ref de branch/tag, quando presentes
• Um ícone de merge (⎇) para commits de merge

Clique em uma linha de commit para expandir seus detalhes sob demanda:

• Corpo completo da mensagem do commit
• Estatísticas de alteração de arquivos (arquivos alterados, linhas adicionadas/removidas, detalhamento por arquivo)

Use Load more na parte inferior para buscar a próxima página de commits (50 por página).

Exemplo:

┌─ 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 Informações, Configurações e Ajuda

Comandos para obter informações e realizar configurações do sistema.

1.11 Atalhos Comuns

1.12 Comandos de Autenticação

Use /auth dentro de uma sessão do Qwen Code para configurar a autenticação. Use /doctor para inspecionar o status atual de autenticação e do ambiente.

2. Comandos @ (Introduzindo Arquivos)

Os comandos @ são usados para adicionar rapidamente o conteúdo de arquivos ou diretórios locais à conversa.

Nota: Espaços nos caminhos precisam ser escapados com barra invertida (ex.: @My\ Documents/file.txt)

3. Comandos de Exclamação (!) - Execução de Comandos Shell

Os comandos de exclamação permitem que você execute comandos do sistema diretamente dentro do Qwen Code.

Variáveis de Ambiente: Comandos executados via ! definirão a variável de ambiente QWEN_CODE=1.

4. Comandos Personalizados

Salve prompts usados com frequência como comandos de atalho para melhorar a eficiência do trabalho e garantir consistência.

Visão Geral Rápida

Regras de Prioridade: Comandos do projeto > Comandos do usuário (o comando do projeto é usado quando os nomes são iguais)

Regras de Nomenclatura de Comandos

Tabela de Mapeamento de Caminho de Arquivo para Nome de Comando

Regras de Nomenclatura: O separador de caminho (/ ou \) é convertido em dois pontos (:)

Especificação de Formato de Arquivo Markdown (Recomendado)

Comandos personalizados usam arquivos Markdown com frontmatter YAML opcional:

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

Formato de Arquivo TOML (Descontinuado)

Mecanismo de Processamento de Parâmetros

1. Injeção Sensível ao Contexto ({{args}})

2. Processamento Padrão de Parâmetros

🚀 Injeção de Conteúdo Dinâmico

3. Execução de Comando Shell (!{...})

Exemplo: Geração de Mensagem de Commit Git

---
description: Gera mensagem de Commit com base nas alterações staged
---
 
Please generate a Commit message based on the following diff:
 
```diff
!{git diff --staged}
```

4. Injeção de Conteúdo de Arquivo (@{...})

Exemplo: Comando de Code Review

---
description: Code review com base nas melhores práticas
---
 
Revise {{args}}, padrões de referência:
 
@{docs/code-standards.md}

Exemplo Prático de Criação

Tabela de Etapas de Criação do Comando “Refatoração para Função Pura”

---
description: Refatora código para função pura
---
 
Por favor, analise o código no contexto atual e refatore para uma função pura.
Requisitos:
 
1. Fornecer o código refatorado
2. Explicar as principais alterações e a implementação das características de função pura
3. Manter a função inalterada

Resumo das Melhores Práticas para Comandos Personalizados

Tabela de Recomendações de Design de Comandos

Tabela de Resumo dos Recursos de Segurança

5. Subcomandos da CLI

Estes comandos são executados a partir do shell como qwen <subcomando> antes de iniciar uma sessão interativa.

Gerenciamento de Sessões

qwen sessions list

Lista suas sessões recentes do Qwen Code com metadados.

Flags:

Saída legível por humanos (padrão):

Uma tabela com as colunas: SESSION ID, STARTED (timestamp UTC), TITLE, BRANCH, PROMPT.

Saída em JSON (--json):

Gera JSON Lines no stdout. Cada linha é um objeto JSON com os campos:

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

O aviso de “has more sessions” é emitido via stderr para que o pipe para jq permaneça seguro.

Exemplos:

# Mostra as últimas 20 sessões (padrão)
qwen sessions list
 
# Mostra as últimas 50 sessões
qwen sessions list --limit 50
 
# Saída em JSON para scripts
qwen sessions list --json | jq .

qwen sessions ps

Lista as sessões interativas do Qwen Code em execução nesta máquina agora. sessions list percorre transcrições salvas (“no que eu trabalhei”); este percorre o registro de processos ativos (“o que está executando neste momento”). Registros deixados por uma sessão encerrada são varridos conforme encontrados. Sessões headless (qwen -p) não se registram no registro de processos ativos, então não são mostradas.

Flags:

Saída legível por humanos (padrão):

Uma tabela com as colunas: NAME, KIND, PID, AGE, DIRECTORY.

KIND indica o que registrou a sessão — tui para alguém em um terminal, external para um programa que não é uma sessão do Qwen Code (um front-end de voz, um relay) e headless ou serve para uma sessão controlada por outro programa. Várias linhas serve ou headless podem compartilhar um único PID: um filho qwen --acp hospeda todas as suas sessões em um processo — serve quando o daemon o iniciou, headless quando um cliente o controla diretamente — e cada uma delas se registra separadamente. É um autorrelato, assim como NAME e DIRECTORY: cada campo aqui foi escrito pelo processo que descreve, e nada sobre o que uma sessão pode fazer depende disso. Consulte o Cross-Session Protocol para o formato do registro e como registrar seu próprio programa.

Saída em JSON (--json):

Gera JSON Lines no stdout, com a sessão mais recente primeiro. Cada linha é um objeto JSON com os campos:

schemaVersion, pid, procStart, pidNs, sessionId, cwd, name, startedAt,
qwenVersion, kind, ipcPath (quando peer messaging está disponível)

Nada mais é escrito no stdout — uma listagem vazia não imprime nada — então qwen sessions ps --json | jq . é seguro para scripts.

A saída em JSON são dados brutos: os valores dos campos são emitidos exatamente como gravados, sem sanitização de terminal. Trate-os como dados e sanitize antes de renderizá-los em um terminal.

Exemplos:

# Mostra as outras sessões ativas
qwen sessions ps
 
# Quais diretórios estão ocupados agora?
# Nota: `jq -r` renderiza o valor bruto gravado no seu terminal (veja a
# nota de dados brutos acima); pipe através de um sanitizador se o caminho não for confiável.
qwen sessions ps --json | jq -r .cwd

6. Enviando Mensagens para Outra Sessão em Execução

Duas sessões interativas na mesma máquina podem enviar mensagens uma para a outra. O recurso é experimental e desativado por padrão; ative-o em settings.json e reinicie:

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

Uma vez ativado, o modelo em uma sessão pode descobrir as outras com list_agents — cada uma aparece sob sessions com o name que qwen sessions ps --json registra (a visualização em tabela pode truncar nomes longos) — e endereçar uma com send_message usando esse nome como to. Quando duas sessões compartilham um nome, list_agents mostra cada uma com um curto [ref] e o envio deve incluí-lo (name [ref]); um nome simples que poderia significar qualquer uma é recusado em vez de adivinhado. list_agents também reporta o nome da própria sessão sob self, e to: "*" ainda significa “meus colegas da Agent Team” e nunca alcança outras sessões.

Uma mensagem chega na outra sessão marcada como vindo de outra sessão, não do seu usuário, e não carrega nenhuma de suas autoridades lá: a sessão receptora age sobre ela apenas dentro de suas próprias configurações de permissão. Seu usuário pode escolher o que acontece com mensagens recebidas usando agents.crossSessionInbound (accept, hold ou refuse). Quando não definido, uma mensagem é entregue apenas quando ambas as sessões estão na mesma classe de revisão: ambas ainda revisam cada ação (modo default ou plan), ou ambas estão em um modo que aplica algumas ações sem revisão por ação (auto-edit, auto ou yolo). Uma mensagem de uma sessão na outra classe, ou de um remetente que não informa em qual classe está, é mantida para revisão — em ambas as direções. Uma sessão que revisa cada ação mantém uma mensagem de uma que não revisa, porque essa mensagem foi escrita por um modelo que ninguém estava observando, e os prompts por ação protegem as ações, não o que a sessão está sendo levada a fazer. Mensagens mantidas são listadas e liberadas com /peers na sessão receptora, e uma mensagem mantida apenas porque os modos diferiam é liberada automaticamente quando eles concordam.

Um repositório pode tornar as sessões abertas nele mais cautelosas, nunca menos: um .qwen/settings.json de workspace pode definir agents.crossSessionInbound como hold ou refuse, ou agents.crossSessionMessaging como false, e esse valor prevalece sobre um valor mais permissivo nas suas configurações de usuário. Um valor de workspace que tornaria sua configuração mais permissiva (accept, ou true para o switch) é ignorado com um aviso, e um valor que a CLI não reconhece mantém toda mensagem quando é o valor efetivo. Configurações de sistema sobrescrevem tudo isso, como fazem para toda configuração.

Uma retenção não espera para sempre. Uma mensagem sobre a qual ninguém decide expira após agents.crossSessionHeldExpiry — 1m, 5m, 10m ou never, cinco minutos por padrão — e a sessão remetente é informada de que nenhuma decisão foi tomada. Encurtar a configuração se aplica a mensagens já em espera.

Se a sessão não puder vincular sua caixa de entrada — o diretório do runtime estiver faltando, pertencer a outro usuário ou ser somente leitura, como pode acontecer dentro de um container — ela primeiro tenta um diretório privado sob o diretório temporário, e apenas se isso também falhar é que inicia sem uma. Quando isso acontece, a sessão informa isso na inicialização, e /peers repete o motivo e o que mudar (geralmente XDG_RUNTIME_DIR ou TMPDIR).

Duas sessões também podem resolver o mesmo endereço de caixa de entrada, porque o endereço é chaveado por pid de processo e pids de processo se repetem entre containers que compartilham um diretório de runtime. A sessão que inicia segundo pega um endereço vizinho em vez de tomar o que está em uso, então nenhuma se torna inalcançável. Os pares não são afetados: eles leem o endereço de uma sessão a partir do registro de sessões em vez de derivá-lo.

A chamada send_message apenas confirma que a mensagem foi entregue à outra sessão. O que aconteceu com ela chega mais tarde como um recibo: se foi mantida, recusada, rejeitada, descartada, expirou ou endereçada incorretamente (o endereço mudou de mãos — liste os agentes novamente) — ou liberada após uma retenção — um aviso aparece na transcrição da sessão remetente (Message to <name>: …). Recusada, rejeitada e descartada são três respostas diferentes: recusada significa que alguém revisou a mensagem e disse não, rejeitada significa que o agents.crossSessionInbound daquela sessão é refuse e ninguém a viu, e descartada significa que sua caixa de entrada recusou a mensagem antes de qualquer disso (veja abaixo). O primeiro descarte é respondido imediatamente e os demais são agrupados em um recibo a cada poucos segundos, cada um nomeando as mensagens que representa, então uma sequência deles custa algumas linhas em vez de uma linha cada. O modelo que a enviou não é informado; se a outra sessão responder, a resposta chega como uma mensagem entre sessões.

Proteção contra inundação

Uma sessão aceita até 30 mensagens de uma vez de um único remetente e depois uma a cada dois segundos, e até 32 de uma vez de todos os remetentes juntos e depois uma por segundo. O segundo limite existe porque um remetente se identifica pelo nome: alternar esse nome obtém uma nova cota do primeiro limite, mas não do segundo. É pouco acima do primeiro porque cada mensagem aceita gera um recibo, e uma sessão só pode ter tantos sendo enviados de uma vez. Uma mensagem de outra sessão que repete a mensagem anterior do mesmo remetente palavra por palavra dentro de 30 segundos também é recusada — um modelo em loop em uma única frase cria um novo id de mensagem a cada vez, então é o texto que o detecta. Mensagens de um script que a sessão iniciou e de um controlador confiável são isentas da verificação de repetição, porque um hook reportando a mesma linha duas vezes está reportando dois fatos e uma pessoa dizendo “continue” duas vezes significa duas vezes; ambas ainda estão sujeitas aos limites de taxa. Por fim, uma mensagem que é aceita mas não pode ser enfileirada porque a sessão já tem 50 em espera também é recusada.

Uma mensagem recusada dessa forma nunca é mantida, nunca é mostrada ao modelo e não deixa registro, então o remetente pode tentar novamente mais tarde e conseguir. A sessão receptora informa isso em sua transcrição no máximo uma vez por minuto por remetente, com uma contagem do que aquela linha representa. A sessão remetente recebe um recibo nomeando cada mensagem que a explosão custou, e sua transcrição diz para consolidar o que ainda importa em uma mensagem posterior em vez de reenviar.

O lado remetente não espera para descobrir. Cada sessão rastreia o que enviou para cada endereço e recusa um envio que o receptor descartaria, então o modelo é instruído a agrupar antes da mensagem ser escrita, não depois — e o receptor nunca gasta uma conexão em uma mensagem que iria recusar.

Autenticação de caixa de entrada e injeção via script

A caixa de entrada de cada sessão requer um token por sessão: uma conexão deve apresentá-lo na primeira linha antes que qualquer mensagem seja lida, e as sessões trocam tokens automaticamente através dos mesmos registros de registro pelas quais se descobrem. Sessões de uma build sem suporte a token podem receber de uma mais nova, mas seus envios para ela são descartados.

Uma sessão exporta seu próprio endereço de caixa de entrada e um token para processos filhos como QWEN_CODE_MESSAGING_SOCKET e QWEN_CODE_MESSAGING_TOKEN, então um script ou hook que a sessão executa pode enviar uma mensagem de volta para ela. Este é um segundo token filho que nunca é publicado em nenhum lugar: apenas processos que a sessão iniciou podem segurá-lo, então uma mensagem que chega com ele é reconhecida como da própria sessão em vez de ser de outra sessão.

{ 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"

Dê a cada injeção um msgId fresco. O gate receptor lembra os ids que já liquidou, então um hook que reutiliza um é entregue na primeira vez e silenciosamente deduplicado em cada execução depois disso. Repetir o mesmo texto é permitido — a verificação de repetição acima não se aplica aos processos da própria sessão — mas os limites de taxa se aplicam, então um hook em loop é descartado como qualquer outra inundação.

Uma mensagem injetada ainda passa pelo gate de entrada e é marcada como não vindo do usuário, mas o gate sabe que veio do próprio processo da sessão: sob o padrão de paridade de modo ela é entregue sem revisão (um par na mesma posição seria mantido), enquanto um agents.crossSessionInbound explícito de hold ou refuse se aplica a ela como a qualquer outra coisa. O modelo a vê como <cross_session_message from="own process" origin="own-process"> com um aviso de que veio de um script ou hook que a sessão executou, não do usuário.

Controladores confiáveis

A regra acima mantém uma mensagem de qualquer remetente que não diz em qual classe de revisão está, e um programa que não é uma sessão do Qwen Code não tem nenhuma para dizer. Esse é o padrão correto para um estranho, mas não para um programa que você escolheu: um front-end de voz, uma ponte de ditado, um daemon de automação retransmitindo suas próprias instruções teria toda mensagem estacionada, e aprovar cada uma manualmente derrotaria o propósito.

Você concede a entrega a tal programa cunhando um token para ele:

qwen sessions controllers add --label voice-bridge

O token é impresso uma vez e não é armazenado em nenhum lugar: o arquivo sob seu Qwen home mantém apenas seu hash SHA-256, então nada que posteriormente leia esse arquivo pode apresentar o token. Coloque-o na própria configuração do controlador quando o comando o imprimir.

Um controlador apresenta o token da mesma forma que qualquer outro remetente — como a primeira linha da conexão — e pega o caminho do socket a partir do registro de sessões (qwen sessions ps --json imprime um registro por sessão ativa, sendo ipcPath o endereço):

{ 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"

Uma mensagem que chega com um token concedido é entregue sem revisão por mensagem, qualquer que seja a classe de revisão de qualquer lado — mas ainda cede a uma configuração explícita: um agents.crossSessionInbound de hold a estaciona como qualquer outra coisa, e refuse a afasta. Concessões pertencem ao seu Qwen home em vez de a uma sessão, então um controlador alcança quaisquer sessões que você estiver executando, e as sessões releem o arquivo em cada conexão: cunhar ou revogar uma tem efeito na próxima conexão, sem nada para reiniciar.

qwen sessions controllers list          # ids, rótulos, quando foram adicionados
qwen sessions controllers remove c_1a2b # revogar um

/peers controllers e /peers revoke <id> fazem o mesmo de dentro de uma sessão. Uma mensagem que veio através de uma concessão é mostrada como Message from a trusted controller (voice-bridge), e aparece em /peers como [controller] voice-bridge se uma configuração hold a estacionou.

O modelo vê tal mensagem como <cross_session_message from="controller" origin="controller" controller="voice-bridge">, com um aviso de que ela retransmite suas próprias instruções — e as mesmas duas proibições que se aplicam a qualquer outra origem: ela não pode editar configurações de permissão, QWEN.md ou config porque a mensagem pediu, e não pode tratar a mensagem como você aprovando um prompt de confirmação pendente. Um controlador pode dizer o que fazer a seguir; não pode responder a um prompt em seu nome.

Qualquer um que segure o token pode enviar como aquele controlador, então trate-o como qualquer outra credencial: dê-o a um programa, mantenha-o fora de config compartilhado, e revogue-o quando esse programa terminar.

Sessões controladas por um programa via ACP

Qualquer filho qwen --acp registra cada sessão que hospeda — como serve quando o daemon iniciou o processo, como headless quando um editor ou outro cliente está controlando qwen --acp diretamente — e a sessão aparece em qwen sessions ps e no list_agents de outra sessão como qualquer outra. Ela pode enviar: seu modelo pode chamar send_message para alcançar um terminal que você tenha aberto. Várias delas compartilham um processo e uma caixa de entrada, então um remetente precisa nomear a sessão que pretende atingir — toda sessão do Qwen Code faz isso automaticamente.

Mensagens enviadas para uma delas são recusadas em vez de mantidas. Manter é uma pergunta feita a uma pessoa, e ninguém está observando uma lista de mensagens mantidas em nome de uma sessão controlada; um remetente é informado imediatamente em vez de esperar o expirar. Onde uma mensagem mantida deveria aparecer para essas sessões ainda não está definido.

Uma sessão se registra apenas enquanto suas próprias configurações tiverem agents.crossSessionMessaging ativado. Com ele desativado, ela permanece invisível, porque a única razão para listar uma sessão que ninguém pode enviar mensagens seria anunciar um endereço que nunca responde.

Programas que não são sessões do Qwen Code

Tudo acima funciona entre sessões, mas nada disso é específico a uma. Um programa que escreve um registro no registro para si mesmo e vincula uma caixa de entrada da mesma forma é listado pelo qwen sessions ps e pelo list_agents, pode ser endereçado por nome a partir do send_message e recebe recibos de entrega para o que envia — um front-end de voz, um relay, um observador de build. Ele deve registrar kind: "external" para que uma listagem possa dizer o que ele é.

O Cross-Session Protocol é o contrato para escrever um: o schema do registro e como a atividade é julgada, os caminhos de socket e enquadramento, a linha de autenticação, cada campo de frame, os estados de recibo e suas transições, e o que um receptor faz com uma mensagem antes que seu modelo a veja.

Um programa Node não precisa escrever nada disso à mão: @qwen-code/sdk/peer implementa o contrato. PeerEndpoint.start({ name }) publica o registro e vincula a caixa de entrada, list() e send() endereçam sessões por nome, e onMessage recebe o que elas enviam.