在脚本中运行 Qoder CLI

概述

Headless（非交互）模式让 Qoder CLI 在没有交互式界面的情况下运行——接收一个提示词，执行任务，把结果输出到标准输出，然后退出。它适合把 Qoder 嵌入 Shell 脚本、自动化流程和 CI/CD 流水线。进入 Headless 模式的方式是加上 --print（简写 -p）：

qodercli -p "解释这个代码仓库的架构"

由于没有人在旁边确认，Headless 模式下的权限需要预先配置好——任何原本需要弹窗确认的操作，在纯文本 Headless 模式下会被自动拒绝。相关说明见权限。

基本用法

把提示词作为参数传入，并加上 -p：

qodercli -p "生成本次改动的提交信息"

也可以通过标准输入传入提示词：

echo "总结昨天的所有代码变更" | qodercli -p

在脚本中捕获输出：

result=$(qodercli -p "列出 src 目录下所有导出的函数")
echo "$result"

输出格式

用 --output-format（简写 -o）指定输出格式，默认是 text：

格式	说明	适用场景
`text`	纯文本结果（默认）	直接阅读、简单脚本
`json`	单个 JSON 对象，包含结果和元数据	需要程序化解析最终结果
`stream-json`	逐条输出的 JSON 消息流	需要实时消费中间过程

示例：

# 纯文本（默认）
qodercli -p "解释 main.ts 的作用"

# JSON：便于脚本解析
qodercli -p "解释 main.ts 的作用" --output-format json

# Stream JSON：实时消费消息流
qodercli -p "重构 utils 模块" --output-format stream-json

输入格式可以用 --input-format 指定，支持 text 和 stream-json。使用 stream-json 输入时，可以通过标准输入持续发送结构化消息。

常用参数

Headless 模式下常配合以下参数使用：

参数	说明
`-p, --print`	打印响应并退出（非交互）
`-o, --output-format <format>`	输出格式：text / json / stream-json
`--input-format <format>`	输入格式：text / stream-json
`--max-turns <count>`	限制单次查询的最大对话轮数
`--permission-mode <mode>`	设置权限模式
`--allowed-tools <tool>`	仅允许指定工具
`--disallowed-tools <tool>`	禁止指定工具
`-m, --model <model>`	指定模型
`--session-id <id>`	使用指定的会话 id
`-w, --cwd <dir>`	启动前切换工作目录

完整参数见 CLI 启动参数参考。

权限控制

Headless 模式下没有交互式确认，因此需要通过权限参数预先决定哪些操作可以自动执行：

# 文件编辑自动通过，Shell 命令仍被拒绝
qodercli -p "重构 utils 模块" --permission-mode accept_edits

# 只放行特定工具
qodercli -p "检查状态" --allowed-tools 'Read,Bash(git status)'

# 全部放行（仅限可信场景）
qodercli -p "执行数据库迁移" --yolo

在纯文本 Headless 模式下，任何"需要确认"的操作默认转为拒绝；若由宿主程序通过 stream-json 协议驱动（例如 Agent SDK），确认请求会转交宿主程序决策，见权限中"不同运行环境下 ask 的消费方式"。
用 --permission-mode accept_edits 可自动批准工作目录内的安全文件编辑。
用 --yolo（等价于 --permission-mode bypass_permissions）跳过所有确认，仅建议在完全可信的环境中使用。

各权限模式的行为详见权限。

CI/CD 示例

在流水线中，通常先通过环境变量完成认证，再以 Headless 模式运行：

export QODER_PERSONAL_ACCESS_TOKEN="your_token"

qodercli -p "审查本次改动并列出潜在问题" \
  --output-format json \
  --permission-mode accept_edits \
  --max-turns 20

认证方式见登录与认证。把输出格式设为 json，便于流水线后续步骤解析 Qoder 的结果。