Codex 使用与会话管理指南
# Codex 使用与会话管理指南
Codex 可以围绕代码仓库阅读文件、修改代码、运行命令并验证结果。CLI 提供终端交互入口，桌面 App 提供图形界面；使用哪个入口，与正在处理哪一段对话是两件事。官方 CLI 说明 (opens new window)
本文核对日期：2026-10-17；终端命令参考本机 codex-cli 0.162.1 的帮助输出。不同客户端的命令入口可能不同，先以当前版本帮助和 / 菜单为准。
开始一个仓库任务
在普通 shell 中执行：
| 命令 | 用途 |
|---|---|
codex --version | 查看 CLI 版本 |
codex --help | 查看本机支持的参数 |
codex | 在当前目录启动交互界面 |
codex -C /path/to/repo | 指定工作目录 |
codex resume | 选择已有对话 |
codex resume --all | 跨目录列出对话，避免被当前目录筛选隐藏 |
codex resume THREAD_ID | 恢复指定 ID 的对话，先将占位符替换为实际值 |
任务描述应包含目标、影响范围、约束和验收方式。例如：“补充 AI 工具文档，保留旧链接；检查 Markdown 链接、标签和示例语法，完成后提交。”仓库约定写入 AGENTS.md，可复用操作流程参见 AI Skill 实践。
CLI、App 与终端怎样关联
对话由 Thread ID / Chat ID 标识。客户端进程只是访问入口；同一个进程可以切换对话，同一个目录也可以保存多段对话。官方 App Server 使用 thread/start 创建对话，用 thread/resume 和 threadId 恢复已有对话。Thread 接口说明 (opens new window)
| 对象 | 表示什么 | 能否唯一定位一段对话 |
|---|---|---|
| CLI / App 客户端 | 用户与 Codex 交互的界面 | 不能 |
| 进程 PID | 当前运行的进程 | 不能，重启后可能变化 |
| 项目目录 / worktree | 文件和 Git 工作区 | 不能，同目录可以有多段对话 |
| tmux session / pane | 承载终端的会话与分屏 | 不能 |
| 会话名称 | 方便查找的标题 | 不能，允许修改或重复 |
| Thread ID / Chat ID | 具体对话的标识 | 可以 |
底层协议还有 thread.sessionId，表示当前会话树的根；持久分叉后的 thread 可以保留根的 sessionId。精确对应一段对话时使用 thread.id，不要把这两个字段当作恒等关系。字段定义 (opens new window)
在 CLI 和桌面 App 之间定位对话
以下命令输入到 Codex 对话框，不能直接当作 zsh 命令运行：
| 命令 | 用途 |
|---|---|
/status | 查看会话状态；当前客户端支持时显示 Chat ID |
/model | 查看或切换当前可用模型 |
/plan | 切换规划模式，适合先厘清复杂修改 |
/review | 发起代码审查 |
/rename 名称 | 给当前对话设置易识别的名称 |
/app | 在支持的桌面客户端中打开同一段已保存对话 |
/resume | 在 CLI 内选择已有对话 |
/fork | 从当前历史建立新对话，新对话拥有新的 Thread ID |
/statusline | 配置 CLI 底部状态栏，可显示 session id |
/title | 配置终端标题，可显示 thread、项目和 Git 分支 |
官方当前文档将 /app 的目标称为 ChatGPT 桌面 App；旧版 Codex App 的名称和入口可能不同。若菜单里没有该命令，先用 ID 或名称在当前客户端的历史列表核对，不假定所有版本自动展示相同历史。命令说明 (opens new window)
可用“项目 + 任务”命名，例如 /rename blog-codex-docs，再通过 ID 确认具体对话。不要只靠项目目录或进程数量判断。
查看命令属于哪段对话
Codex 启动的命令子进程中可能带有 CODEX_THREAD_ID。在该命令环境中可执行：
echo "$CODEX_THREAD_ID"
这是本机观察到的环境标识，不应假定所有终端都注入它。启动 CLI 的外层 shell 可能为空；嵌套启动的客户端也可能继承外层值。核对当前 CLI 对话时优先使用客户端状态信息。
下面的换行会先执行空的 echo，再把变量的值当作命令，因此报 command not found：
# 错误示例：两条独立命令
echo
"$CODEX_THREAD_ID"
2
3
结合 tmux 排查
先区分“Codex 对话”和“tmux 连接”两层：
| 现象 | 检查方向 |
|---|---|
| 同目录下有几个 Codex 客户端 | 分别查看对话 ID，不能靠目录判断是否同一段对话 |
tx: command not found | shell 是否加载了自定义函数；tx 是本仓库工具，不是 Codex 内置命令 |
| tmux 报 socket 不存在 | 检查 tmux 服务连接，pane 可见不等于新客户端能连接 |
tx even bottom 操作目标不明确 | 先核对 $TMUX、$TMUX_PANE 与调用窗口 |
本仓库的 tmux socket 诊断与恢复统一维护在 环境配置说明 (opens new window)。恢复 tmux 连接不会改变 Codex 的 Thread ID；恢复 Codex 对话也不会替你恢复已退出的 tmux 服务。
相关文档
- AI 学习入口
- Cursor：IDE 内的规则、子代理和技能配置。
- Claude Code：另一个终端编程工具的入口与模型连接。
- OpenAI 官方 CLI 文档 (opens new window)