第八课：会话管理命令

7.9K字·20分钟·

resumeforkarchivedeleteunarchive

1. 概述

Codex CLI 的会话管理系统允许你保存、恢复、分支和管理与 Codex 的对话历史。这对于以下场景至关重要：

长时间任务：大型重构可能需要多次会话才能完成
上下文保留：避免每次都从零开始解释项目背景
并行探索：从同一个起点分叉出多个探索方向
历史回溯：查看和恢复之前的对话

会话数据存储在本地，每个会话都有唯一的 ID 和元数据（创建时间、工作目录、使用的模型等）。

2. 会话存储位置

2.1 存储路径

Codex 的会话数据存储在 ~/.codex/sessions/ 目录下：

~/.codex/
├── sessions/
│   ├── session_abc123.json      # 会话数据
│   ├── session_def456.json
│   └── ...
├── profiles/                     # Profile 配置
├── instructions.md               # 全局自定义指令
└── config.json                   # 全局配置

每个会话文件包含：

会话 ID：唯一标识符
消息历史：完整的对话记录
元数据：创建时间、工作目录、模型、token 使用量等
状态：active / archived / deleted

2.2 存储格式

会话文件使用 JSON 格式存储：

{
  "id": "session_abc123",
  "created_at": "2026-06-28T10:00:00Z",
  "updated_at": "2026-06-28T11:30:00Z",
  "working_directory": "/home/user/my-project",
  "model": "o4-mini",
  "status": "active",
  "messages": [
    {
      "role": "user",
      "content": "帮我重构 utils.py",
      "timestamp": "2026-06-28T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "好的，我来分析 utils.py 的结构...",
      "timestamp": "2026-06-28T10:00:05Z"
    }
  ],
  "metadata": {
    "total_tokens": 50000,
    "files_changed": ["utils.py", "helpers.py"],
    "commands_run": ["pytest tests/"]
  }
}

3. `codex resume`：恢复会话

3.1 基本用法

codex resume 用于恢复一个之前的会话，继续之前的对话上下文：

# 恢复指定会话
codex resume session_abc123

# 使用会话 ID 的前缀（自动匹配）
codex resume abc123

恢复后，Codex 会：

加载完整的对话历史
恢复工作目录上下文
你可以继续之前的对话，Codex 记得之前的所有讨论

3.2 `--last` 参数：恢复最近会话

# 恢复最近一次会话
codex resume --last

# 简写形式
codex resume -l

这是最常用的恢复方式，适合以下场景：

中途退出后继续工作
第二天继续昨天的任务
意外断开后恢复

3.3 列出可恢复的会话

# 列出所有活跃会话
codex sessions list

# 列出所有会话（包括归档的）
codex sessions list --all

# 按工作目录过滤
codex sessions list --dir /home/user/my-project

# 最近 10 个会话
codex sessions list --limit 10

输出示例：

ID              Updated              Dir                        Model     Messages
─────────────────────────────────────────────────────────────────────────────────
abc123          2026-06-28 11:30     ~/my-project               o4-mini   42
def456          2026-06-28 10:00     ~/another-project          gpt-4.1   15
ghi789          2026-06-27 18:00     ~/my-project               o3        128

3.4 会话恢复的注意事项

工作目录必须存在：如果原工作目录已被删除，恢复会失败
文件状态不恢复：会话只恢复对话历史，不恢复文件的修改状态
模型可能变化：如果默认模型已更改，恢复后会使用新模型
上下文可能过时：如果文件在会话后被修改，Codex 的上下文可能不准确

4. `codex fork`：分支会话

4.1 基本用法

codex fork 从一个现有会话创建一个新的分支会话，保留原会话的所有历史但开始新的对话：

# 从指定会话分叉
codex fork session_abc123

# 从最近的会话分叉
codex fork --last

# 分叉时添加初始 prompt
codex fork session_abc123 "换一种方式实现这个功能"

4.2 分叉的应用场景

场景 1：探索不同方案

原始会话 (abc123):
  用户: 帮我设计一个用户认证系统
  Agent: 我建议使用 JWT + Redis 方案...

分叉 1 (fork_001):
  继续: 实现 JWT + Redis 方案

分叉 2 (fork_002):
  继续: 考虑使用 Session + Cookie 方案

场景 2：从错误中恢复

# 原始会话走偏了，分叉一个新的从正确的地方开始
codex fork session_abc123 "从我们讨论数据库设计的地方重新开始，这次用 PostgreSQL 而不是 MongoDB"

场景 3：并行实验

# 同时尝试两种重构策略
codex fork session_abc123 "用函数式编程风格重构"   # fork_001
codex fork session_abc123 "用面向对象风格重构"     # fork_002

4.3 分叉与恢复的区别

特性	`resume`	`fork`
原会话	继续原会话	原会话不变
新会话	不创建	创建新会话
对话历史	包含	包含（从分叉点开始）
适用场景	继续中断的工作	探索不同方向

5. `codex archive`：归档会话

5.1 基本用法

codex archive 将会话标记为归档状态，从活跃列表中移除但不删除数据：

# 归档指定会话
codex archive session_abc123

# 归档最近的会话
codex archive --last

# 批量归档（归档所有超过 7 天的会话）
codex sessions archive --older-than 7d

5.2 归档的作用

保持列表整洁：活跃会话列表只显示当前相关的会话
不丢失数据：归档的会话随时可以恢复
提高性能：减少活跃会话数量可以加快列表加载

5.3 查看归档会话

# 列出归档的会话
codex sessions list --archived

# 搜索归档会话
codex sessions search "数据库设计" --archived

6. `codex unarchive`：取消归档

6.1 基本用法

codex unarchive 将归档的会话恢复为活跃状态：

# 取消归档指定会话
codex unarchive session_abc123

# 通过关键词查找并取消归档
codex sessions search "认证系统" --archived
# 找到 session_abc123
codex unarchive abc123

6.2 自动恢复

取消归档后，会话会重新出现在活跃列表中，可以直接 resume：

codex unarchive abc123
codex resume abc123

7. `codex delete`：删除会话

7.1 基本用法

codex delete 永久删除一个会话：

# 删除指定会话（会要求确认）
codex delete session_abc123

# 强制删除（不询问确认）
codex delete session_abc123 --force

# 删除最近的会话
codex delete --last

7.2 批量删除

# 删除所有归档的会话
codex sessions delete --archived

# 删除超过 30 天的会话
codex sessions delete --older-than 30d

# 删除特定目录的所有会话
codex sessions delete --dir /tmp/test-project

7.3 删除的注意事项

⚠️ 删除操作不可逆：

会话数据会从磁盘永久删除
无法通过 unarchive 恢复
建议先 archive，确认不需要后再 delete

8. `codex sessions`：会话管理命令组

8.1 子命令列表

codex sessions list       # 列出会话
codex sessions search     # 搜索会话
codex sessions info       # 查看会话详情
codex sessions export     # 导出会话
codex sessions import     # 导入会话
codex sessions clean      # 清理过期会话

8.2 搜索会话

# 按关键词搜索
codex sessions search "数据库优化"

# 按时间范围搜索
codex sessions search --from 2026-06-01 --to 2026-06-28

# 按工作目录搜索
codex sessions search --dir ~/my-project

# 按模型搜索
codex sessions search --model o3

8.3 查看会话详情

# 查看会话元数据
codex sessions info session_abc123

# 输出示例：
# Session: session_abc123
# Created: 2026-06-28 10:00:00
# Updated: 2026-06-28 11:30:00
# Directory: /home/user/my-project
# Model: o4-mini
# Messages: 42
# Status: active
# Token Usage: 50,000 (input: 35,000, output: 15,000)
# Files Changed: utils.py, helpers.py

8.4 导出与导入

# 导出会话为 JSON 文件
codex sessions export session_abc123 -o backup.json

# 导出所有会话
codex sessions export --all -o all_sessions.tar.gz

# 导入会话
codex sessions import backup.json

9. 最佳实践

9.1 会话命名与组织

虽然 Codex 自动生成会话 ID，但你可以通过以下方式组织会话：

# 在会话开始时说明任务目标
codex "【用户认证模块】实现 JWT 认证和刷新 token 机制"

# 后续通过搜索找到
codex sessions search "用户认证模块"

9.2 定期清理

# 每周清理一次过期会话
codex sessions clean --older-than 7d --archive

# 每月彻底删除归档会话
codex sessions delete --archived --older-than 30d

建议的清理策略：

7 天后归档：不活跃的会话自动归档
30 天后删除：归档超过 30 天的会话永久删除
重要会话导出：特别重要的会话导出备份

9.3 工作流示例

日常开发工作流：

# 早上开始工作
codex resume --last  # 继续昨天的工作

# 午饭前归档当前会话
codex archive --last

# 下午开始新任务
codex "实现新的 API 端点"

# 需要探索不同方案时
codex fork --last "用 GraphQL 替代 REST"
codex fork --last "用 gRPC 替代 REST"

# 选择最佳方案后，归档其他分支
codex archive fork_001

大型项目工作流：

# 按模块组织会话
codex "【模块A】重构用户服务"    # session_A
codex "【模块B】优化查询性能"    # session_B
codex "【模块C】添加缓存层"      # session_C

# 按模块搜索
codex sessions search "模块A"

# 项目完成后批量归档
codex sessions archive --dir ~/project-x

9.4 故障恢复

# 意外退出后恢复
codex resume --last

# 如果恢复失败，尝试查看会话状态
codex sessions info $(codex sessions list --limit 1 | awk '{print $1}')

# 如果会话损坏，从导出的备份恢复
codex sessions import backup_2026-06-27.json

10. 高级用法

10.1 会话链

通过 fork 可以创建会话链，实现复杂的多阶段任务：

# 阶段 1：需求分析
codex "分析用户需求，制定技术方案"  # session_001

# 阶段 2：数据库设计（从阶段 1 分叉）
codex fork session_001 "设计数据库 schema"  # session_002

# 阶段 3：API 开发（从阶段 2 分叉）
codex fork session_002 "实现 REST API"  # session_003

# 阶段 4：前端开发（从阶段 1 分叉，跳过数据库设计）
codex fork session_001 "实现前端页面"  # session_004

10.2 会话标签

# 给会话添加标签
codex sessions tag session_abc123 "重要"
codex sessions tag session_abc123 "用户认证"

# 按标签搜索
codex sessions search --tag "重要"

# 按标签批量操作
codex sessions archive --tag "已完成"

10.3 会话统计

# 查看会话统计
codex sessions stats

# 输出示例：
# Total Sessions: 156
# Active: 12
# Archived: 144
# Total Tokens Used: 2,500,000
# Average Session Duration: 25 minutes
# Most Active Directory: ~/my-project (45 sessions)

思考题

resume 和 fork 的核心区别是什么？在什么场景下应该使用 fork 而不是 resume？
如果你正在处理一个大型重构任务，需要尝试多种不同的实现方案，你会如何使用会话管理命令来组织你的工作？
会话数据存储在本地有什么优缺点？如果要在团队中共享会话，你会如何设计？
如何设计一个自动化脚本，定期清理过期会话同时保留重要的历史会话？
如果会话的工作目录被意外删除，会话数据还能恢复吗？应该如何处理这种情况？