docs: add tmux codex workflow article

2026-05-13 14:47:06 +08:00
parent 85f8926aca
commit 8989bbc413
3 changed files with 322 additions and 0 deletions
@@ -275,6 +275,18 @@ export default sidebar({
        },
      ],
    },
+    {
+      text: 'Codex',
+      icon: 'fa6-solid:terminal',
+      collapsible: true,
+      children: [
+        {
+          text: 'tmux + Codex 终端会话管理实战',
+          icon: 'mdi:console',
+          link: 'tmux-codex-workflow.md',
+        },
+      ],
+    },
    {
      text: 'ChatGPT',
      icon: 'fa6-solid:comments',
@@ -18,6 +18,7 @@ tag:
 - OpenCode CLI 实战指南
 - OpenCode TUI 实战指南
 - Claude Code 多分支工作流实战总结（2026）
+- tmux + Codex 终端会话管理实战
 - ChatGPT 使用记录与实践
 - OpenClaw 个人 24 小时在线部署实战
 - iFlow 流程编排实践记录
@@ -0,0 +1,309 @@
+---
+title: tmux + Codex 终端会话管理实战
+icon: mdi:console
+date: 2026-05-13
+category:
+  - AI
+  - 开发工具
+  - Linux
+tag:
+  - tmux
+  - Codex
+  - 终端
+  - AI编程
+  - Linux
+---
+
+# tmux + Codex 终端会话管理实战
+
+Codex 很适合在终端里处理长任务，但如果直接跑在普通 shell 里，
+终端关闭、SSH 断开、临时切换任务都会影响体验。tmux 的价值就是把
+终端会话托管起来：任务可以留在后台，回来以后继续接着看。
+
+<!-- more -->
+
+---
+
+## 一、为什么 Codex 适合搭配 tmux
+
+使用 Codex 时，经常会遇到这些场景：
+
+1. 让 Codex 分析一个较大的仓库，需要等一段时间。
+2. 跑构建、测试、日志排查时，需要同时看多个终端。
+3. 通过 SSH 连服务器，网络一断，普通终端里的任务就中断了。
+4. 临时去处理别的事情，回来后希望会话还在原来的状态。
+
+tmux 正好解决这些问题。
+
+一句话概括：tmux 是终端里的会话管理器。
+
+它提供的核心能力包括：
+
+- 后台会话：命令继续留在服务器或本机终端环境里。
+- 断开恢复：退出终端后，还可以重新 attach 回去。
+- 多窗口：一个会话里管理多组任务。
+- 多分屏：同一个屏幕里同时放 Codex、测试、日志、Git 命令。
+
+对 Codex 这类终端 AI 工具来说，tmux 最大的意义不是炫技，而是稳定。
+
+---
+
+## 二、安装与验证
+
+Ubuntu / Debian 系统可以直接安装：
+
+```bash
+sudo apt install tmux
+```
+
+如果遇到软件源连接失败，尤其是阿里云源、公司内网源或临时网络问题，
+可以先更新索引：
+
+```bash
+sudo apt update
+sudo apt install tmux
+```
+
+如果仍然失败，再检查当前源是否可用，必要时切换到更稳定的软件源。
+
+安装完成后查看版本：
+
+```bash
+tmux -V
+```
+
+能看到类似下面的输出，就说明安装成功：
+
+```text
+tmux 3.4
+```
+
+---
+
+## 三、Codex 推荐启动方式
+
+日常最推荐的方式是：一个项目一个 tmux 会话。
+
+进入项目目录后创建名为 `codex` 的会话：
+
+```bash
+tmux new -s codex
+```
+
+进入 tmux 后再启动 Codex：
+
+```bash
+codex
+```
+
+需要临时离开时，不要直接关闭终端，而是 detach：
+
+```text
+Ctrl+b  松开后按 d
+```
+
+注意这里不是一直按住 `Ctrl+b+d`，而是先按 `Ctrl+b`，松开，再按 `d`。
+
+回来时重新连接：
+
+```bash
+tmux attach -t codex
+```
+
+查看当前有哪些会话：
+
+```bash
+tmux ls
+```
+
+任务结束后关闭会话：
+
+```bash
+tmux kill-session -t codex
+```
+
+这一套命令已经能覆盖大部分 Codex 使用场景。
+
+---
+
+## 四、常用快捷键
+
+tmux 默认前缀键是 `Ctrl+b`。多数操作都遵循同一个节奏：
+
+```text
+先按 Ctrl+b，松开，再按目标键
+```
+
+常用快捷键如下：
+
+| 操作 | 快捷键 |
+| --- | --- |
+| 新建窗口 | `Ctrl+b c` |
+| 左右分屏 | `Ctrl+b %` |
+| 上下分屏 | `Ctrl+b "` |
+| 切换分屏 | `Ctrl+b 方向键` |
+| 轮流切换窗格 | `Ctrl+b o` |
+| 关闭当前分屏 | `Ctrl+b x` |
+| 离开当前会话 | `Ctrl+b d` |
+
+其中有两个键容易误解：
+
+- `%` 实际是 `Shift+5`。
+- `"` 实际是 `Shift+'`。
+
+所以左右分屏不是按一个独立的百分号键，而是在 `Ctrl+b` 之后按
+`Shift+5`。
+
+---
+
+## 五、Codex 里的翻页和滚动问题
+
+Codex TUI 会接管终端里的上下键、滚轮和部分显示区域，所以在普通终端里
+习惯的滚动方式，进入 tmux + Codex 后可能会变得不顺手。
+
+如果要查看 tmux 的历史输出，可以进入复制模式：
+
+```text
+Ctrl+b [
+```
+
+进入后可以使用：
+
+- `PageUp` / `PageDown` 翻页。
+- 方向键上下移动。
+- `q` 退出复制模式。
+
+如果希望 Codex 的输出尽量保留在终端滚动历史里，可以考虑这样启动：
+
+```bash
+codex --no-alt-screen
+```
+
+`--no-alt-screen` 的作用是避免使用独立的 alternate screen，更适合需要
+保留历史输出、经常回看上下文的终端工作流。
+
+我的建议是：
+
+- 长任务、远程 SSH、需要恢复会话时，用 `tmux + codex`。
+- 需要频繁回看大量历史输出时，优先尝试 `codex --no-alt-screen`。
+- 如果已经在 tmux 里，掌握 `Ctrl+b [` 是最关键的滚动技巧。
+
+---
+
+## 六、实际踩坑总结
+
+### 1. `Ctrl+b d` 没反应
+
+大多数时候是按法不对。
+
+正确节奏是：
+
+```text
+按 Ctrl+b
+松开
+再按 d
+```
+
+tmux 的很多快捷键都不是三键同时按，而是“前缀键 + 指令键”。
+
+### 2. 分屏快捷键按不出来
+
+左右分屏：
+
+```text
+Ctrl+b %
+```
+
+这里的 `%` 是 `Shift+5`。
+
+上下分屏：
+
+```text
+Ctrl+b "
+```
+
+这里的 `"` 是 `Shift+'`。
+
+### 3. 后台会话太多
+
+先查看：
+
+```bash
+tmux ls
+```
+
+再按会话名清理：
+
+```bash
+tmux kill-session -t 会话名
+```
+
+例如：
+
+```bash
+tmux kill-session -t codex
+```
+
+### 4. 快捷键只有在 tmux 里才生效
+
+`tmux ls` 能看到后台会话，不代表当前终端已经在 tmux 里。
+
+判断方式很简单：如果底部有 tmux 状态栏，通常说明你正在 tmux 会话里；
+如果没有状态栏，先执行：
+
+```bash
+tmux attach -t codex
+```
+
+进入会话后再使用 `Ctrl+b` 系列快捷键。
+
+---
+
+## 七、推荐日常工作流
+
+我的日常使用方式可以压缩成三条：
+
+1. 一个项目一个 tmux 会话。
+2. 左边跑 Codex，右边跑测试、日志、Git 命令。
+3. 长任务全部放进 tmux，避免终端关闭或 SSH 断开导致中断。
+
+一个典型启动流程如下：
+
+```bash
+cd /path/to/project
+tmux new -s codex
+codex --no-alt-screen
+```
+
+进入后可以左右分屏：
+
+```text
+Ctrl+b %
+```
+
+左侧保持 Codex 对话，右侧执行：
+
+```bash
+git status
+npm run docs:build
+tail -f app.log
+```
+
+这样终端不再只是一个输入命令的地方，而是一个可恢复、可拆分、
+可长期运行的工作台。
+
+---
+
+## 八、总结
+
+tmux 本身并不复杂，真正需要记住的只有几件事：
+
+- `tmux new -s codex`：创建会话。
+- `Ctrl+b d`：离开但不关闭。
+- `tmux attach -t codex`：回到会话。
+- `Ctrl+b %` / `Ctrl+b "`：左右或上下分屏。
+- `Ctrl+b [`：查看历史输出。
+
+如果你经常在终端里使用 Codex，尤其是在远程服务器或长任务场景下，
+tmux 基本属于必备工具。它不改变 Codex 的能力，但能明显提升会话稳定性、
+任务恢复能力和多终端协作效率。