TUI 模式
在任意项目根目录运行 qoderclicn 即可进入默认的 TUI(交互式)模式。可以通过文本与 CLI 对话,或使用斜杠命令执行特定功能。
输入模式
TUI 提供多种输入模式:
| 命令 | 描述 |
|---|---|
> | 对话模式(默认)。输入任意文本即可与 CLI 对话 |
! | Bash 模式。在对话模式下输入 ! 可直接运行 shell 命令 |
/ | 斜杠模式。在对话模式下输入 / 可打开并运行内置命令 |
\⏎ | 按 Enter 开始多行输入 |
内置工具
Qoder CN CLI 内置 Grep、Read、Write、Bash 等工具,可用于文件/目录操作和 shell 命令执行。
斜杠命令
通过以下内置斜杠命令可快速访问功能和设置:
| 命令 | 描述 |
|---|---|
/login | 登录你的 Qoder CN 账号 |
/help | 显示 TUI 帮助 |
/init | 在项目中初始化或更新 AGENTS.md 记忆文件 |
/memory | 打开记忆概览,管理用户级、项目级、本地记忆和自动记忆入口 |
/quest | 执行基于 Spec 的委派任务 |
/review | 对本地代码改动进行评审 |
/resume | 查看并恢复会话 |
/clear | 清除当前会话的历史上下文 |
/compact | 总结当前会话的历史上下文 |
/usage | 显示当前 Credits 使用情况 |
/status | 查看 CLI 状态,包括版本、模型、账号、API 连通性、工具状态等 |
/config | 查看 Qoder CN CLI 的系统配置 |
/effort | 调整当前模型的思考深度及相关模型参数 |
/agents | 子代理命令:查看、创建、管理子代理 |
/tasks | 查看当前正在运行的后台任务 |
/release-notes | 显示 Qoder CN CLI 的更新日志 |
/vim | 打开外部编辑器以编辑输入 |
/feedback | 发送 Qoder CN CLI 相关反馈 |
/quit | 退出 TUI |
/logout | 退出你的 Qoder CN 账号 |
高级启动选项
启动 CLI 时,可使用以下选项控制其行为:
| 命令 | 说明 | 示例 |
|---|---|---|
-w | 指定工作区目录 | qoderclicn -w /Users/demo/projects/nacos |
-c | 继续上次会话 | qoderclicn -c |
-r | 恢复指定会话 | qoderclicn -r *******-c09a-40a9-82a7-a565413fa39 |
--allowed-tools | 仅允许指定工具 | qoderclicn --allowed-tools=Read,Write |
--disallowed-tools | 禁止指定工具 | qoderclicn --disallowed-tools=Read,Write |
--max-turns | 最大对话轮数 | qoderclicn --max-turns=10 |
--yolo | 跳过权限检查 | qoderclicn --yolo |
Print 模式
Print 模式为非交互式模式。运行 qoderclicn --print 进入该模式,输出将按 --output-format 参数指定的格式打印。
参数
全局参数可用于任意命令:
| 参数 | 说明 | 示例 |
|---|---|---|
-p | 以非交互方式运行 Agent | qoderclicn -q -p hi |
--output-format | 输出格式:text、json、stream-json | qoderclicn --output-format=json |
-w | 指定工作区目录 | qoderclicn -w /Users/qoder_user/projects/qoder_demo |
-c | 继续上次会话 | qoderclicn -c |
-r | 恢复指定会话 | qoderclicn -r ********-c09a-40a9-82a7-a565413fa393 |
--allowed-tools | 仅允许指定工具 | qoderclicn --allowed-tools=Read,Write |
--disallowed-tools | 禁止指定工具 | qoderclicn --disallowed-tools=Read,Write |
--max-turns | 最大对话轮数 | qoderclicn --max-turns=10 |
--yolo | 跳过权限检查 | qoderclicn --yolo |
MCP 服务
Qoder CN CLI 可以连接 Model Context Protocol(MCP)服务,以使用外部工具和数据源。添加服务后,其中的工具会在交互式和非交互式会话中提供给 Agent 使用。
快速开始
使用 qoderclicn mcp add 添加 stdio MCP 服务。-- 后面的命令是 Qoder CN CLI 需要启动的服务进程。
/mcp reload 重新发现 MCP 服务和工具;新的会话会在启动时自动发现。
服务类型
使用 -t 选择 MCP 传输类型。
| 类型 | 适用场景 |
|---|---|
stdio | MCP 服务作为本地命令运行 |
sse | MCP 服务通过 Server-Sent Events 端点暴露 |
http | MCP 服务通过 HTTP 端点暴露 |
ws | MCP 服务通过 WebSocket 端点暴露 |
作用域
使用 -s 选择 MCP 服务配置的保存位置。
| 作用域 | 适用场景 |
|---|---|
user | 希望该服务在当前账号的所有项目中可用 |
local | 希望该服务只在本机当前项目中可用。默认作用域为 local |
project | 希望该服务配置随项目共享 |
管理服务
列出已配置的服务:
推荐服务
常见 MCP 服务包括:
MCP 权限
MCP 工具仍会经过 Qoder CN CLI 的权限系统。在默认模式下,调用 MCP 工具通常会请求确认。你可以批准某个具体工具、批准某个 MCP 服务下的所有工具,或在 settings 中配置规则。MCP 工具名通常使用以下格式:
故障排查
如果 MCP 工具不可用:
- 运行
qoderclicn mcp list,确认服务已经配置。 - 如果 Qoder CN CLI 已在运行,添加或修改服务后执行
/mcp reload。 - 确认
--后面的命令可以在终端中正常运行。 - 对于基于
npx的服务,确认 Node.js 和网络访问可用。 - 如果服务已连接但工具调用被阻止,请检查权限提示。
权限
Qoder CN CLI 对工具的执行具有细粒度权限控制,可覆盖文件读写、Bash 命令、Web 抓取、MCP 工具、子代理以及其他内置工具。
权限模式
权限模式决定了 Qoder CN CLI 如何处理工具调用——每种模式在"自动化程度"和"安全宽松度"两个维度上定位不同。
| 模式 | 适用场景 | 行为 |
|---|---|---|
default | 常规交互式使用 | 安全读取和内部动作可自动执行;敏感操作请求确认。 |
accept_edits | 日常编码任务 | 自动批准工作目录内的安全文件编辑;Shell 命令、外部动作和敏感路径仍走正常检查。 |
auto | 自动化运行、Goal 执行 | 零弹窗。安全读取和工作区内编辑自动批准;风险动作被拒绝或交给 AI 分类器判断。 |
bypass_permissions(YOLO) | 仅用于可信本地实验 | 跳过所有批准提示。所有工具调用自动放行。 |
dont_ask | 必须不弹窗的 headless 流程 | 从不询问。任何原本需要询问的动作都会被拒绝。 |
Plan 与 Goal 模式
Plan 是独立的工作状态(非权限策略),可与上述任意权限模式共存。通过 /plan 命令进入/退出(toggle)。进入后 Qoder CN CLI 只读探索代码并输出方案,写入受限于计划文件。
Goal 是自主执行状态。通过 /goal set <目标> 进入——自动切换到 auto 模式并锁定 Shift+Tab 切换。使用 /goal clear 或 /goal pause 退出。
在交互式会话中,按 Shift+Tab 在所有权限模式间循环切换;按 Ctrl+Y 可直达 YOLO 模式。
启动参数
使用 --permission-mode 选择当前会话的默认行为:
accept_edits / acceptEdits、bypass_permissions / bypassPermissions / yolo、dont_ask / dontAsk。
权限如何决策
Qoder CN CLI 在每次工具调用前做权限检查。权限结果只有三种:allow(立即执行)、ask(需要外部确认)、deny(阻止执行)。
决策顺序:
- 先检查
deny规则——命中即拒绝。 - 工具自身的安全检查(如危险命令检测、敏感路径检测)。
ask规则——命中则标记为需要确认。- 工具级
allow规则和模式带来的自动允许行为。 - 如果最终结果仍是
ask,由运行环境决定如何消费。
| 运行环境 | ask 的归宿 | 说明 |
|---|---|---|
| TUI(交互式终端) | 弹窗确认 | 用户在终端中选择允许/拒绝。 |
Headless(-p/--prompt) | 自动拒绝 | 无人交互,ask 转为 deny。 |
| SDK(stdio 协议) | 发送 canUseTool 回调给宿主 | 宿主程序决定 allow/deny。 |
| ACP(IDE 集成) | 发送 requestPermission RPC 给 IDE | IDE 弹窗或自动决策。 |
配置来源与优先级
规则从多个来源合并,按优先级从低到高,共 8 层:
| 层级 | 来源 | 说明 |
|---|---|---|
| 1 | userSettings | ~/.qoder-cn/settings.json(用户全局) |
| 2 | projectSettings | /.qoder/settings.json(项目级,团队共享) |
| 3 | localSettings | /.qoder/settings.local.json(本机个人,加入 .gitignore) |
| 4 | flagSettings | --settings CLI 参数指定的文件 |
| 5 | cliArg | --allowed-tools / --disallowed-tools 命令行参数 |
| 6 | command | /allow、/deny 会话中命令 |
| 7 | session | 运行时临时规则(弹窗中"本次会话允许") |
allowManagedPermissionRulesOnly,则只使用策略托管的规则。
模式配置
设置默认模式——在 ~/.qoder/settings.json 中配置 general.defaultPermissionMode:
权限规则配置
Qoder CN CLI 通过三种核心策略进行权限控制:Allow、Deny 和 Ask。相关配置文件按优先级递增如下:
allow、ask 和 deny 分组:
| 形式 | 含义 |
|---|---|
ToolName | 作用于整个工具。 |
ToolName(content) | 作用于某个路径、命令、agent 类型,或工具支持的其他特定内容。 |
* | 匹配所有工具。 |
Read、Edit、Write、Bash、Grep、Glob、WebFetch、WebSearch、Agent,以及 mcp__github__create_issue 这类 MCP 工具名。
命令行覆盖:
信任目录
Qoder CN CLI 将启动时的当前工作目录(CWD)视为主信任目录。在信任目录内:文件读取默认 allow;文件写入在 accept_edits 和 auto 模式下可自动批准;非默认权限模式(auto、bypass 等)才能生效。
如果当前目录不被信任,Qoder CN CLI 会强制回退到 default 模式。通过 --add-dir、/add-dir 命令或 permissions.additionalDirectories 增加额外可信工作目录:
.git、.vscode、.idea、.husky、大多数 .qoder 配置文件、.bashrc/.zshrc 等 shell 启动文件、Git 配置、.mcp.json、.ripgreprc。在常规交互式模式下,这些路径需要明确批准;在 auto 模式下会被拒绝。
文件访问规则
读取与编辑(Read & Edit) 读取规则适用于所有读文件的工具(如 Grep、Glob 等);编辑规则适用于 Edit、Write 和 NotebookEdit。文件规则使用 gitignore 风格匹配。
| 模式 | 含义 |
|---|---|
/src/** | 基于规则来源根目录的路径。在 project/local settings 中相对于项目根目录;在 user settings 中相对于 home 目录。 |
~/Documents/** | 基于 home 目录的路径。 |
//tmp/data/** | 从系统 / 开始的绝对路径,需要使用双斜杠。 |
*.secret | 不带根目录的文件名模式,可在任意位置匹配。 |
Bash 规则
Bash(...) 规则可以匹配精确命令、命令前缀或通配模式:
Bash(npm run build)精确匹配npm run buildBash(npm run test:*)匹配以npm run test开头的命令Bash(git log *)使用 glob 风格通配匹配
deny 和 ask 规则会穿透常见 wrapper 和环境变量前缀;前缀和通配 allow 规则不会静默批准复合命令;危险命令(如破坏性删除或 force push),即使存在宽泛 allow 规则,也可能强制确认。在 auto 模式下,危险 Shell 命令会被拒绝。
Web 和 MCP 规则
WebFetch 限制网络抓取工具可访问的域名。例如 WebFetch(domain:example.com) 将抓取限制为 example.com。
MCP MCP 工具使用完整限定名 mcp__<server>__<tool>;可用 mcp__github__* 匹配某个 server 的所有工具,或使用 mcp__* 匹配所有 MCP 工具。若需限定本次运行只启用指定 MCP server,可使用 --allowed-mcp-server-names:
Hook 与权限
Qoder CN CLI 的 Hook 系统在权限决策链路中有两个注入点:PreToolUse(工具执行前)和 PermissionRequest(权限管道产出 ask 之后、弹窗前)。Hook 的权限决策优先级高于权限模式——即使在 bypass_permissions 模式下,PreToolUse Hook 返回 deny 仍然会阻止执行。详见钩子。
Worktree
使用 --worktree [name] 可以在独立的 Git worktree 中启动 Qoder CN CLI 会话。适合在同一个仓库中并行处理多个任务,避免多个会话共享同一个工作目录。
在 worktree 中启动
手动删除 worktree
如需手动删除 worktree,执行:
记忆
Qoder CN CLI 每次会话都会重新构造上下文。需要跨会话保留的知识主要来自两类记忆:
AGENTS.md文件:由你或团队维护的持久指令,适合放开发规范、项目结构、常用命令和协作约定。- 自动记忆:启用后由 Qoder CN CLI 在本机保存的 Markdown 记忆,适合记录后续会话仍有用的偏好、反馈、项目背景和外部参考。
AGENTS.md 常用位置
| 位置 | 用途 | 是否适合提交 |
|---|---|---|
~/.qoder-cn/AGENTS.md | 当前用户跨项目通用偏好和工作习惯 | 否 |
${project}/AGENTS.md | 团队共享的项目规则、架构说明、常用命令 | 是 |
${project}/AGENTS.local.md | 当前机器上的项目私有说明,例如本地服务地址或个人测试数据 | 否 |
${project}/.qoder/rules/*.md | 按主题或文件范围拆分的项目规则 | 是 |
context.fileName 设置单个文件名或文件名数组。默认值是 AGENTS.md。
加载逻辑
启动或刷新记忆时,Qoder CN CLI 的项目记忆会向上查找,并检查每一层的项目规则目录:
- 用户级记忆:加载用户配置目录中的
AGENTS.md。 - 项目和本地项目记忆:在可信工作区内,从当前工作区目录向父目录查找
AGENTS.md、AGENTS.local.md和.qoder/rules/**/*.md,默认到.git所在目录为止。 - 没有
pathsfrontmatter 的规则会随项目记忆一起加载;带pathsfrontmatter 的规则只会在 Qoder CN CLI 访问匹配文件后按需加载。 - 子目录记忆:启动时不预加载。只有 Qoder CN CLI 成功读取子目录里的文件后,才会从该文件所在目录向上补充此前未加载的记忆文件。
规则(Rules)
规则是放在 rules/ 目录下、按主题拆分的指令文件,用来替代单个臃肿的 AGENTS.md。规则有两种作用域:
| 作用域 | 位置 | 作用范围 | 是否提交 |
|---|---|---|---|
| 项目级 | ${project}/.qoder/rules/**/*.md | 文件所在的项目,与团队共享 | 是 |
| 用户级 | ~/.qoder-cn/rules/**/*.md | 你打开的每个项目,仅限本机个人使用 | 否 |
paths frontmatter 决定它何时加载:没有 paths 时始终生效;带 paths 时按路径生效。示例:
管理与自动记忆
在 TUI 中输入 /memory 打开记忆概览,管理用户级、项目级和本地记忆文件;执行 /init 会在项目目录中生成 AGENTS.md。
自动记忆只在交互式会话中运行,通过环境变量启用:
~/.qoder-cn/projects/<project>/memory/;启用用户级后还会使用 ~/.qoder-cn/memory/。启用后可在 /memory 面板打开 auto-memory folder,也可输入 /memory manage 管理自动保存的记忆文件。
导入其他文件
AGENTS.md 可以用 @path/to/file 引入其他文件。相对路径基于当前 AGENTS.md 所在目录解析。支持相对路径、绝对路径和 ~/ 路径;行内代码或代码块中的 @... 不会被识别为导入。
子代理
子代理(Subagent)是 Qoder CN CLI 中专门处理特定类型任务的 Agent。每个子代理拥有独立的对话上下文、工具集合、模型配置、权限模式和运行限制,适合把代码探索、方案设计、接口审查、测试补齐等工作拆给更聚焦的执行者。在 TUI 中执行 /agents 打开配置面板即可查看、创建和管理子代理。完整能力、来源优先级、配置字段和使用方式请参见子代理。
命令
命令(斜杠命令)是 Qoder CN CLI 中唤起特定任务的快捷方式,通过斜杠符号(/)前缀触发。在 TUI 模式下输入 / 可查看可用命令清单并选择执行;无头模式(Headless)也支持执行会提交提示词的命令。
命令类型
| 类型 | 说明 | 适用模式 | 扩展性 |
|---|---|---|---|
| TUI 类型 | 提供交互式界面(如弹出对话框、列表选择) | TUI | 系统内置,不支持自定义 |
| Prompt 类型 | 向对话中提交预设提示词,指导 CLI 完成特定任务 | TUI + Headless | 支持用户自定义扩展 |
内置命令
Qoder CN CLI 提供的常用内置命令:
命令 | 类型 | 用途 |
| TUI | 查看和管理 Subagent 清单,支持创建、编辑 Subagent 配置 |
| TUI | 查看和管理后台任务 |
| TUI | 打开动态工作流任务面板 |
| TUI | 清除当前对话内容,开始新的对话 |
| TUI | 查看和管理自定义命令,支持创建、编辑命令配置 |
| Prompt | 压缩对话历史,可指定关注重点 |
| TUI | 配置管理,查看或修改 Qoder CN CLI 配置项 |
| TUI | 导出当前会话到文件 |
| TUI | 提交反馈或报告问题 |
| TUI | 显示帮助信息 |
| TUI | 初始化项目,分析项目结构并生成 |
| TUI | 登录 Qoder CN CLI 账号 |
| TUI | 登出 Qoder CN CLI 账号 |
| TUI | MCP 服务管理 |
| TUI | 打开记忆概览;自动记忆启用时可打开 auto-memory folder,或用 |
| TUI | 查看和管理模型级别设置 |
| TUI | 设置当前模型的思考深度;不传 level 时打开模型参数面板 |
| TUI | 设置当前模型的上下文窗口;不传参时打开模型参数面板 |
| TUI | 开关当前模型的快速模式;不传参时打开模型参数面板 |
| Prompt | 智能工作流编排器,多个智能体协同工作,协助用户完成功能开发 |
| TUI | 退出 Qoder CN CLI |
| TUI | 查看版本更新说明 |
| TUI | 恢复之前的会话或对话历史,支持 Tab 键分页切换会话 |
| Prompt | 执行代码审查,检查代码质量和规范性 |
| TUI | GitHub 集成配置,设置 GitHub 相关功能 |
| TUI | 管理当前工作区的 Skill 命令 |
| TUI | 查看当前会话状态和系统信息 |
| TUI | 升级订阅计划 |
| TUI | 查看使用情况统计,包括 Token 消耗等信息 |
| TUI | 启用或配置 Vim 模式,提供 Vim 风格编辑体验 |
创建自定义命令
Qoder CN CLI 支持创建 Prompt 类型的自定义命令,通过配置文件定义命令的名称、描述和系统提示词。命令配置文件为 Markdown 格式,包含 frontmatter 元数据和系统提示词:
name(必填)——命令的唯一名称,用于 /command-name 调用;description(必填)——命令的功能描述,支持多行文本(使用 YAML 语法)。
命名规范:使用小写字母和连字符(例如 git-commit);避免使用空格或特殊字符;建议文件名与 name 字段保持一致;子目录中的命令使用 : 作为命名空间分隔符(例如 commands/git/commit.md 注册为 /git:commit);同目录下若存在 SKILL.md,该目录会注册为单个命令,其它兄弟 .md 文件会被忽略。
存储位置与优先级
命令配置文件可以存储在项目级或用户级目录中:
| 级别 | 路径 | 生效范围 | 提交到代码仓库 |
|---|---|---|---|
| 项目级 | .qoder/commands/<command_name>.md | 仅当前项目 | 建议提交(团队共享) |
| 用户级 | ~/.qoder-cn/commands/<command_name>.md | 所有项目 | 不提交(个人配置) |
/commands 即可重新加载。
示例
按以下方式定义一个命令,并将其保存到 ~/.qoder-cn/commands/quest.md 中。
/quest 触发命令,命令执行过程中会按照提示词先后调用两个子代理完成任务。
相关文档
- 模型
- 子代理
- 技能
- 钩子
- ACP
- Remote Control