CodeCLI Command Reference

中文 README · English README · Architecture

本文档是命令行为、常见用法与通道差异的事实来源。README 只保留入口和速查摘要。

使用约定

所有带 [id] 的命令都可以省略 id，省略时默认作用于当前活跃会话
直接输入普通文本，会发送到当前活跃会话
Telegram 与 WeChat 默认采用 clean-result delivery：普通文本和未知 slash fallback 成功后不回即时 [session N] sent，而是在 turn 完成/确认/终态节点回有效结果
HTTP 保留即时发送确认，CLI 与嵌入式 Tool API 也保留同步确认；如需实时过程输出，请显式使用 /watch
投递是 best effort：内存 pending、事件队列、通道注销、过期和连续传输失败都可能导致结果丢弃，不是持久化 exactly-once 保证
输出模式优先级固定为：/send --output ... 单次 override > /mode session 默认 > automatic policy > 系统默认 result
automatic policy 已对高置信测试、全局搜索和明显长任务生效；短问答、控制输入和普通短任务继续保持 result 或默认回退
automatic policy 只作为显式控制之外的补充层，不会覆盖 /send --output、/mode，也不会替代 /watch
/status、/info 和 Tool structured response 会显示当前 output mode 的 source；automatic 命中时还会暴露命中的规则名
session owner / result-owner 属于 chat channel 路由策略；它决定默认状态通知与显式 handoff，不会阻止其他通道显式向会话发送消息
/1 hello 表示把 hello 直接发送给会话 1
/1 如果后面不带文本，则会显示会话 1 的状态
路径中有空格时请使用引号，例如 /cd "dir with spaces"
p1、p2 是 worked_path 自动生成的目录别名
一部分简单命令支持省略前导 /，例如 claude、help、paths、status、ping、cat
这些命令都支持目录别名：/claude p1、/codex p2、/cd p1、/ls p1、/start python -m http.server --cwd p1
如果启用了消息验证门控，需先发送 /auth <password>

快捷启动

命令	说明
`/claude [cwd]`	在指定目录启动 Claude Code
`/cursor [cwd]`	在指定目录启动 Cursor Agent
`/cursor-plan [cwd]`	以 Cursor Plan 模式启动，先规划再动手
`/cursor-ask [cwd]`	以 Cursor Ask 模式启动，只读问答
`/cursor-resume [chat-id] [cwd]` / `/cursor-resume [chat-id] --cwd <path>`	恢复最近或指定的 Cursor 会话
`/cursor-worktree [name] [cwd]` / `/cursor-worktree [name] --cwd <path>`	以 Cursor worktree 模式启动独立工作树
`/cursor-model <model> [cwd]`	使用指定模型启动 Cursor
`/cursor-ls`	列出可恢复的 Cursor 会话
`/cursor-models`	列出当前账号可用的 Cursor 模型
`/codex [cwd]`	在指定目录启动 Codex CLI
`/opencode [cwd]`	在指定目录启动 OpenCode
`/bash [cwd] [cmd]`	启动交互式 Bash；可附带初始命令
`/start <tool	command...> [--cwd path]`
`/clis`	打开 Telegram CLI 工具菜单；本地则列出可用工具

补充：

/start 支持 shell 风格引号解析
/start cursor --plan --cwd p1、/start cursor --mode ask --cwd p1 会通过 Cursor 官方 CLI 参数启动
/start cursor --workspace p1 --cwd /tmp 也支持，p1 会解析为保存过的目录别名
Tool 模式下，/claude、/cursor、/cursor-plan、/cursor-ask、/cursor-resume、/cursor-worktree、/cursor-model、/codex、/opencode、/start ... --cwd <path> 这类 AI CLI 启动命令都必须显式传 path；/bash 仍可沿用当前默认目录

消息与确认

命令	别名	说明
直接输入文本	-	发送到当前活跃会话
`/1 text`	-	发送到会话 1
`/2 text`	-	发送到会话 2
`/send [id	#id] [--output result	stream] `
`/send [id] -- <text>`	-	`--` 之后一律按正文处理，用于发送以数字开头、或本身含 `--` 的文本
`/mode [id] [result	stream]`	-
`/y [id]`	`/a`	发送 `y`，常用于确认
`/n [id]`	`/q`	发送 `n`，常用于拒绝

按键注入

命令	说明
`/enter [id]`	发送回车
`/esc [id]`	发送 Esc
`/tab [id]`	发送 Tab
`/up [id]`	上方向键
`/down [id]`	下方向键
`/space [id]`	空格键
`/key [id] <name>`	发送指定按键，如 `ctrl+c`、`f1`

查看与监控

命令	别名	说明
`/status [id]`	`/s`	查看会话状态，以及 default / effective output 与 source
`/output [id]`	`/o`	查看最近清洗后的输出
`/screen [id]`	-	查看 TUI 渲染屏幕
`/list`	`/l`	列出所有会话
`/all`	-	查看所有会话的详细状态
`/logs [id] [lines]`	`/log` `/lg`	查看会话日志
`/watch [id]`	-	订阅某个会话的实时输出
`/unwatch [id]`	-	取消订阅
`/owner [id]`	-	查看当前 session 的 owner / result-owner / claimable 状态
`/claim [id]`	-	显式认领当前 session 的 owner
`/handoff [id]`	-	主动释放 owner，使其他通道可以 `/claim`

补充：

/output 更适合看最近的有效内容
/screen 更适合看 TUI 当前画面；非 TUI 工具显示最近一次运行输出
/logs 读取的是会话日志文件
当当前已有活跃会话时，/log 50 会理解为“查看当前会话最近 50 行日志”
/watch 是显式高噪声 opt-in，不属于 Telegram 默认 clean-result delivery
result 保持当前 clean-result 语义；stream 只放大当前 preview / 状态投递，不会替代 /watch
automatic stream 主要用于测试命令、全局搜索和明显长任务；短问答或控制输入不会被自动放大
有 pending-send 的通道，最终结果仍优先按原始发送通道回投；owner 不会覆盖 turn-complete provenance
source 可见性遵循真实 resolver decision：例如 session、explicit、automatic:builtin:test_command、automatic:<rule-name>

Output Policy Config

config/codecli.json 可选支持：

{
  "output_policy": {
    "rules": [
      {
        "name": "codex-send-tests",
        "mode": "stream",
        "provider": "codex",
        "commandMode": "send_command",
        "template": "test_command"
      }
    ]
  }
}

当前只支持以下 typed schema：

name: 规则名，也会出现在 source visibility 中
mode: result 或 stream
provider: 可选，匹配当前会话工具
commandMode: 可选，匹配消息入口，例如 direct_text、send_command、confirmation、direct_session_target、slash_fallback、provider_init
template: 可选，匹配内建模板，例如 test_command、repo_search、long_task、short_qa、control_input、confirmation

规则始终只处于 automatic policy 层，不能越过显式 /send --output、/mode 或把 /watch 变成隐式行为。

会话管理

命令	别名	说明
`/use <id>`	-	切换当前活跃会话
`/interrupt [id]`	`/i`	给会话发送中断信号（Ctrl+C）
`/restart [id]`	`/r`	重启某个会话
`/stop [id]`	-	中断当前任务，但保留会话
`/stopall`	-	中断所有会话中的当前任务，但保留会话
`/kill <id>`	-	销毁指定编号的会话
`/kill all`	-	销毁全部会话

规则：

只有显式启动命令才会创建 session：/claude、/cursor、/cursor-plan、/cursor-ask、/cursor-resume、/cursor-worktree、/cursor-model、/codex、/opencode、/bash、/start ...
新启动的 session 会自动把启动通道设为 owner 和 result-owner
/handoff 只释放 owner，不会自动把后续普通消息视为 claim；接管必须显式执行 /claim
/stop、/stopall 只中断任务，不销毁 session
/kill / /kill all 才会销毁 session 并从列表移除
/exit、/reboot 会先停止托管 session，再退出或重启宿主进程
Ctrl+C、程序退出、Telegram / Tool 模式结束时，也会停止当前托管 session
下次启动不会自动恢复旧 session；要继续工作，请重新发送启动命令

工作目录与路径索引

命令	别名	说明
`/cd <path>`	-	切换默认工作目录
`/pwd`	-	查看当前默认工作目录
`/ls [--all] [path]`	-	列出目录内容（默认隐藏 . 开头）
`/paths`	`/path`	查看 `worked_path` 列表和编号
`/pathadd <path>`	-	手动把一个目录加入 `worked_path`
`/pathdel pN`	-	删除一个目录别名
`/pathclear`	-	清空全部已保存目录

关于 worked_path：

进程启动时会先把当前工作目录写入 worked_path
新目录会在 /claude、/cursor、/cursor-plan、/cursor-ask、/cursor-resume、/cursor-worktree、/cursor-model、/codex、/opencode、/bash、/start --cwd、/cd 时自动加入并去重
/paths 会显示 p1、p2 之类的目录别名
删除某个路径后，后面的编号会自动顺延

文件查看

命令	说明
`/cat <file> [from N] [grep keyword]`	查看文件内容并带行号；支持绝对路径、相对 `/cd` 路径、`pN/subpath`

规则：

默认最多直接显示 100 行
超过 100 行时，会进入确认流程，可回复 y、from <N>、grep <关键词>、n
y 在 CLI/Tool 中返回全文；Telegram 的预格式化消息有长度上限，长文件应使用 from <N> 或 grep
from <N> 会从第 N 行开始显示最多 100 行
grep <关键词> 会显示匹配行及前后各 50 行上下文
拒绝读取符号链接文件
文件大小上限为 2MB

Telegram 文件传输

命令	说明
`/file <path> <password>` / `/file pN <subpath> <password>`	仅 Telegram 可用，把指定 Markdown 文件发送到当前聊天

要求：

只允许 .md 文件
口令来自 channels.telegram.<name>.fileTransferPassword；留空即禁用，且不得使用 CHANGE_ME 占位值
文件路径必须位于当前 /cd 目录或某个 worked_path 目录下
文件路径中不允许出现符号链接

系统命令

命令	说明
`/info`	查看启动时间、当前目录、会话数量，以及当前活跃会话的 output/source 摘要
`/ping`	连通测试
`/reboot`	重启 CodeCLI，并停止当前所有会话
`/exit`	停止所有会话并退出
`/help`	查看常用帮助；微信通道返回精简移动版
`/help cursor`	查看 Cursor 高级帮助

补充：

在嵌入式 Tool API 中，/exit 和 /reboot 不会终止宿主进程；请改用 /stopall
python main.py tool 不提供 IPC、HTTP 或 stdin 请求协议；外部 Agent 应使用 create_tool_adapter() 或 create_langchain_tool()

常见流程

本地启动并提问

python main.py cli
/cd "/mnt/d/agent_work/project-a"
/claude
帮我分析这个仓库的目录结构，并给出重构建议

多会话切换

/claude p1
/codex p2
/list
/use 2
帮我给这个项目加测试
/watch 2

Telegram 远程接管

python main.py telegram

然后在 Telegram 里：

默认键盘可先点击 /claude
需要完整工具列表时先发送 /clis
如果 chatId 未配置，默认向 Bot 发送任意消息即可在 120 秒内自动发现并写回 chatId；若额外配置了 channels.telegram.<name>.bindToken（或 bindTokenEnv），则需改为发送 /bind <token> 完成绑定，防止他人抢先绑定
已知 /... 继续走控制命令；未知 /... 会按原文转发到当前活跃会话
普通文本和未知 slash fallback 默认不会立刻回 [session N] sent；完成结果会带 Session N 上下文回到发起聊天
如果需要把默认状态通知交给别的 channel，先在当前 owner 侧执行 /handoff，再由目标 channel 执行 /claim
如果需要实时过程输出，再显式发送 /watch
用 /s、/watch、/y、/n 管理会话
需要回传 Markdown 文件时，使用 /file ...

FilesExpand file tree

command-reference.md

Latest commit

History