Skip to content
FunCoding

Search

Search docs, agents, posts, Skills and MCP servers

无头模式

在脚本和 CI/CD 里非交互运行 Qwen Code：-p/stdin 输入、恢复会话、/goal、覆盖系统提示、输出格式（text/json/stream-json）与退出码。

无头模式让你在命令行脚本和自动化工具里以编程方式运行 Qwen Code，没有任何交互界面。它适合脚本、自动化、CI/CD 流水线，以及构建 AI 驱动的工具：接受命令行参数或 stdin 的提示；返回结构化输出（文本或 JSON）；支持文件重定向和管道；便于自动化和脚本工作流；提供一致的退出码用于错误处理；并能为多步自动化恢复当前项目范围内的之前会话。

基本用法

用 --prompt（或 -p）标志以无头模式运行：qwen --prompt "What is machine learning?"。也可以从 stdin 输入：echo "Explain this code" | qwen；与文件输入组合：cat README.md | qwen --prompt "Summarize this documentation"。

恢复之前的会话：在无头脚本里复用当前项目的对话上下文：

# 继续这个项目最近的会话并运行新的提示
qwen --continue -p "Run the tests again and summarize failures"
# 直接恢复特定的会话 ID（无 UI）
qwen --resume 123e4567-e89b-12d3-a456-426614174000 -p "Apply the follow-up refactor"

会话数据是项目范围的 JSONL，位于 ~/.qwen/projects/<sanitized-cwd>/chats；会在发送新提示之前恢复对话历史、工具输出和聊天压缩检查点。

运行持久的目标

无头模式接受 /goal 作为完整的提示。目标状态与会话一起存储，所以用 --continue 或 --resume <sessionId> 在之后的进程里检查或控制同一个目标（需要 general.chatRecording 启用）。

# 创建目标并启动它的工作者
qwen -p "/goal Finish the release checklist"
# 在同一会话里检查它保存的状态
qwen --continue -p "/goal"

其他操作用同样的 qwen --continue -p "<control>" 模式：/goal（不调用模型就报告保存的状态）；/goal <objective> 或 /goal set …（创建或替换目标并启动无头的目标工作）；/goal edit <objective>（修改未完成的目标，结果状态为活动时立即开始工作）；/goal pause（不调用模型就暂停活动的目标）；/goal resume（恢复符合条件的目标并启动无头的目标工作）；/goal clear（不确认也不调用模型就清除目标）。目标的质量取决于它的完成条件；验证器能判断和不能判断什么见目标文档，可以用 qwen -p "/goal-draft <intent>" 先起草目标。运行时调度的目标延续段不计入 --max-session-turns，但真实的用户提示仍然计入；显式的 --max-wall-time 和 --max-tool-calls 预算继续适用。用 --output-format stream-json 时，每次目标状态变化都发出一个 event.type 为 goal_state 的 stream_event。

自定义主会话提示

你可以为单次 CLI 运行改变主会话系统提示，而不编辑共享的记忆文件。覆盖内置系统提示：用 --system-prompt 替换 Qwen Code 内置的主会话提示：qwen -p "Review this patch" --system-prompt "You are a terse release reviewer. Report only blocking issues."。追加额外指令：用 --append-system-prompt 保留内置提示并为本次运行添加额外指令；两个标志可以组合使用（自定义基础提示加一条运行特定的指令）。注意：--system-prompt 只适用于本次运行的主会话；已加载的记忆和 QWEN.md 这样的上下文文件仍追加在 --system-prompt 之后；--append-system-prompt 在内置提示和已加载的记忆之后应用。选择输出样式：用 --output-style 为本次运行选一个输出样式（内置或自定义）：qwen -p "Why does the build fail on Windows?" --output-style Concise；Learning 样式要求你写部分代码并等待回复，所以在无头运行里被跳过；未知的样式名打印警告并以默认样式继续；当 --system-prompt 或 QWEN_SYSTEM_MD 替换了内置提示时，--output-style 没有效果。

输出格式

  • 文本输出（默认）：标准的人类可读输出，如 qwen -p "What is the capital of France?"。
  • JSON 输出：--output-format json 以 JSON 数组返回结构化数据；所有消息被缓冲并在会话完成时一起输出，适合编程处理和自动化脚本。输出是消息对象数组，包含多种消息类型：系统消息（会话初始化，type: "system"、subtype: "session_start"，带 session_id、model 等）、助手消息（AI 回复，message.content 里是文本块，带 usage）和结果消息（执行结果，type: "result"、subtype: "success"、is_error、duration_ms、result、usage）。
  • Stream-JSON 输出：--output-format stream-json 在执行期间实时、逐行输出 JSON 消息（每条是单独一行上的完整 JSON 对象），便于实时监控；与 --include-partial-messages 组合时，还实时发出额外的流事件（message_start、content_block_delta 等）用于实时 UI 更新。对 JSON 和 stream-JSON 输出，文本的 tool_result.content 值在 JSON 字符串序列化后被限制在 65,536 个 UTF-8 字节以内，超出的会被截断。

退出码

Qwen Code 用特定的退出码指示终止原因，对脚本和自动化尤其有用：41 FatalAuthenticationError（认证过程出错）；42 FatalInputError（给 CLI 的输入无效或缺失，仅非交互模式）；44 FatalSandboxError（沙盒环境出错，如 Docker、Podman 或 Seatbelt）；52 FatalConfigError（配置文件 settings.json 无效或有错误）；53 FatalTurnLimitedError（达到会话的最大对话轮数，仅非交互模式）。