qodercli 命令行全部启动参数、标志、默认值与用法示例
本页列出
当不传入任何参数时，进入交互式会话。传入提示文本或
除启动参数外，
qodercli 命令的全部启动参数与标志。使用 qodercli --help 可在终端查看完整列表。
基本调用形式：
--print 时进入非交互模式。
通用标志
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--version | -v | boolean | 输出版本号并退出。 |
--help | -h | boolean | 显示帮助信息并退出。 |
--debug | -d | boolean | 启用调试日志输出。 |
--cwd | -w | string | 指定工作目录（默认为当前目录）。 |
--config-dir | string | 覆盖用户配置目录（默认 ~/.qoder）。 | |
--add-dir | string[] | 为当前会话添加额外的信任目录（可多次使用）。 | |
--attachment | string | 为初始提示附加文件（可多次使用）。 | |
--worktree | [name] | 在新的 Git Worktree 中隔离执行，结果合并回主分支；名称可选，省略时自动生成。 |
模型与推理
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--model | -m | string | 指定模型标识（如 auto、lite、performance，或 BYOK key）。 |
--reasoning-effort | string | 覆盖本次会话的推理强度（如 high）。 | |
--context-window | number | 覆盖本次会话的上下文窗口大小（token 数）。 | |
--list-models | boolean | 列出可用模型并退出。 | |
--output-style | string | 激活的输出风格名称。 |
会话管理
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--continue | -c | boolean | 继续最近一次会话。 |
--resume | -r | [id] | 按标识恢复历史会话；不带 id 时从列表中选择。 |
--session-id | string | 继续指定 ID 的会话。 | |
--fork-session | boolean | 从恢复的会话中 fork 出新会话（配合 --resume/--session-id）。 | |
--name | -n | string | 设置或覆盖当前会话名称。 |
--list-sessions | boolean | 列出所有历史会话并退出。 | |
--delete-session | <index> | 按序号删除指定会话。 |
冲突规则：--continue、--resume、--remote、--remote-session、--teleport、--remote-control不能同时使用。
输出与脚本模式
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--print | -p | boolean | 非交互模式：输出一次响应后退出（适合 CI/脚本）。 |
--output-format | -o | enum | 输出格式：text（默认）、json、stream-json。 |
--input-format | enum | 输入格式：text（默认）、stream-json。 | |
--max-turns | number | 限制单次查询的最大对话轮数（用于自动化场景防止无限循环）。 | |
--max-output-tokens | number | 设置模型单次输出的最大 token 数。 | |
--prompt-interactive | -i | string | 先执行给定提示词，随后进入交互模式。 |
--no-session-persistence | boolean | 不将会话写入磁盘、无法恢复（仅在 --print 下有效）。 |
权限控制
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--permission-mode | enum | 设置权限模式：default / plan / auto / bypass_permissions / accept_edits / dont_ask。 | |
--yolo | boolean | 等价于 --permission-mode bypass_permissions（危险：跳过所有权限确认）。 | |
--dangerously-skip-permissions | boolean | 等同 --permission-mode bypass_permissions（危险：跳过所有权限确认）。 |
工具与 MCP
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--tools | string[] | 限制可用的内置工具，空格或逗号分隔均可（"" 禁用全部、default 启用全部；用 -p 或 -- 与 query 分隔）。 | |
--allowed-tools | string[] | 允许使用的工具白名单。 | |
--disallowed-tools | string[] | 禁止使用的工具黑名单。 | |
--mcp-config | string | MCP 配置文件路径（JSON）。 | |
--strict-mcp-config | boolean | 严格模式，仅加载 --mcp-config 指定的 MCP 服务器。 | |
--allowed-mcp-server-names | string[] | 允许的 MCP 服务器名称白名单。 | |
--max-model-request-retries | number | Qoder 与外部供应商模型请求的最大重试次数。 |
沙箱
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--sandbox | -s | boolean | 开启沙箱（布尔开关，不接受后端名）。后端由 QODER_SANDBOX 或 tools.sandbox 指定，见 沙箱。 |
Agent 与系统提示
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--agent | string | 指定主线程使用的 Agent 名称。 | |
--agents | json | 以 JSON 对象定义自定义 Agent。 | |
--system-prompt | string | 覆盖系统提示。 | |
--append-system-prompt | string | 在默认系统提示后追加内容。 |
配置覆盖
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--settings | string | JSON 文件路径或内联 JSON 对象（以 { 开头时按内联解析），作为最高优先级配置。 | |
--setting-sources | string[] | 指定加载的配置来源列表。 | |
--plugin-dir | string | 附加插件搜索目录。 |
远程与协作
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--remote | [task] | 创建云端远程会话并打印访问 URL（可选附带初始任务）。 | |
--remote-session | <id> | 冷加载并接入一个已存在的远程会话。 | |
--teleport | <id> | 加载并接入一个远程会话。 | |
--remote-control | <id> | 作为无头 remote-control worker 运行。 |
编辑器集成
| 标志 | 短写 | 类型 | 说明 |
|---|---|---|---|
--acp | boolean | 以 ACP 服务器形式启动，供 Zed 等实现 ACP 协议的客户端通过标准输入输出集成。 |
子命令
除启动参数外，qodercli 还提供若干子命令，形式为 qodercli <子命令>：
| 子命令 | 说明 |
|---|---|
mcp | 配置与管理 MCP 服务器。 |
plugins（别名 plugin） | 管理插件。 |
skills（别名 skill） | 管理 Agent Skills。 |
hooks（别名 hook） | 管理 Hooks。 |
agents（别名 agent） | 管理 Agent。 |
login | 登录账户。 |
commit | 生成提交信息并提交改动。 |
rollback | 回滚到先前版本。 |
update | 更新到最新版本。 |
remote-control | 启动 remote-control 守护进程。 |
status | 显示会话状态。 |
feedback | 提交反馈。 |
wiki | 为项目生成 Wiki 文档。 |
用法示例
下一步
- 交互模式中的斜杠命令：斜杠命令。
- 配置文件与环境变量：配置项、环境变量与文件路径。
- 非交互执行详细指南：在脚本中运行。