LowHow 文档

中文

English

中文

English

深色模式

OpenCode 会话管理实战教程：从入门到数据库维护 ​

📚 分类: AI 工具使用 ⏱️ 预计耗时: 20 分钟 🎯 难度: 入门 🔧 环境要求: 已安装并配置好 OpenCode 终端工具 🌐 原文来源: OpenCode 官方文档 (示例)

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 OpenCode 中“会话”的核心概念和生命周期
  • [ ] 掌握自动压缩、会话切换等高效工作技巧
  • [ ] 学会查看和管理 OpenCode 的 SQLite 数据库
  • [ ] 独立排查会话相关的常见问题

最终效果 ​

你将不再只是被动使用 OpenCode，而是能够主动管理你的 AI 对话历史，理解其背后如何存储、如何计算成本，并能像专家一样进行数据备份、清理和问题排查。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求验证命令
OpenCode已安装opencode --version
SQLite3 (可选)用于数据库操作sqlite3 --version

1. 验证 OpenCode 安装 ​

bash
$ opencode --version    // 验证 OpenCode 是否已安装

✅ 验证：如果看到输出了版本号（如 v0.1.0），说明安装成功。

第 1 步：理解什么是“会话” ​

🎯 目标：掌握 OpenCode 会话的核心概念，理解它为什么是“最基本的组织单元”。

📝 操作： 打开你的终端，启动 OpenCode，并开始一段简单的对话。例如，你可以问它：“Hello, what can you do?”

🤔 为什么要理解会话？ OpenCode 中每一次对话都是一个会话 (Session)。它不仅仅是聊天的记录，更是一个数据容器，包含了：

  • 所有消息：你问的，AI 答的。
  • Token 使用量：输入（prompt）和输出（completion）的 Token 数量。
  • 成本估算：基于使用的模型和 Token 数量计算的费用。
  • 文件变更：AI 帮你创建或修改了哪些文件。
  • 元数据：会话标题、创建时间、父会话 ID 等。

✅ 验证：当你开始对话后，OpenCode 就会在后台自动创建一个新的会话。

第 2 步：掌握会话的生命周期 ​

🎯 目标：了解一个会话从创建到结束的完整过程。

📝 操作： 继续使用 OpenCode 进行对话，观察它的行为。

一个典型的会话生命周期如下：

  1. 创建：当你启动 OpenCode 或创建新对话时 (Ctrl+N)，一个新会话就诞生了。
  2. 活跃：对话进行中，所有消息、Token、成本、文件变更都会被实时记录。
  3. 自动压缩 (可选)：当会话接近模型的上下文窗口限制时（通常是 95%），OpenCode 会自动触发压缩。
  4. 持久化：会话状态会持续保存到 SQLite 数据库中。

✅ 验证： 你可以通过 Ctrl+A 打开会话列表，看看是不是多了一个你刚刚创建的会话记录。

第 3 步：利用“自动压缩”功能 ​

🎯 目标：开启自动压缩，让你的长对话永不中断。

📝 操作：

  1. 打开 OpenCode 的配置文件 ~/.opencode/opencode.json。
  2. 确保 autoCompact 设置为 true。
json
{
  "autoCompact": true  // 开启自动压缩功能
}

🤔 自动压缩是如何工作的？ 当你的对话消耗的 Token 达到模型上下文窗口的 95% 时，OpenCode 会：

  1. 生成摘要：AI 会自动为当前对话生成一个总结，包含关键决策、结果、当前状态等。
  2. 创建新会话：基于这个摘要，创建一个新的子会话。
  3. 无缝衔接：你感觉不到任何中断，可以继续对话，而新会话的 Token 计数器已经重置。

✅ 验证： 当你进行一个超长对话时，如果看到类似“Auto-compacting session...”的提示，就说明功能正在工作。

⚠️ 常见错误： 如果你发现对话突然停止并提示“Context window limit reached”，请检查 autoCompact 是否被错误地设置为 false。

第 4 步：学会快速切换会话 ​

🎯 目标：在多个任务之间快速切换，而不是每次都从头开始。

📝 操作：

  1. 在 OpenCode 中，按下快捷键 Ctrl+A 打开会话列表。
  2. 你会看到最近的会话列表，按时间倒序排列。
  3. 使用上下箭头键或 j / k 键进行导航。
  4. 选中目标会话，按下 Enter 键即可切换过去。

✅ 验证：切换后，你会发现对话上下文已经变成了你之前与该会话的对话内容。

第 5 步：探索 SQLite 数据库 ​

🎯 目标：了解数据是如何存储的，并学会查看和管理它们。

OpenCode 使用 SQLite 数据库 (~/.opencode/opencode.db) 来存储所有会话数据。

📝 操作：

  1. 打开数据库：

    bash
    $ sqlite3 ~/.opencode/opencode.db   // 使用 sqlite3 打开数据库

  2. 查看表结构：

    sql
    sqlite> .tables   // 列出所有表

    你会看到 sessions, messages, files, file_versions 等表。

  3. 执行查询：

    sql
    -- 查看最近 10 个会话的 ID、标题、消息数和成本
sqlite> SELECT id, title, message_count, cost
   ...> FROM sessions
   ...> ORDER BY updated_at DESC
   ...> LIMIT 10;

-- 查看所有消息的总数
sqlite> SELECT COUNT(*) FROM messages;

-- 查看所有会话的总成本
sqlite> SELECT SUM(cost) FROM sessions;

✅ 验证：你应该能看到类似表格的数据输出，这证明你成功连接到了数据库并执行了查询。

第 6 步：进行数据库维护 ​

🎯 目标：学会备份、清理和优化数据库，保证系统健康运行。

📝 操作：

  1. 备份数据库 (重要！)：

    bash
    # 创建一个带时间戳的备份
$ cp ~/.opencode/opencode.db ~/.opencode/opencode.db.$(date +%Y%m%d).backup

  2. 清理旧会话： 删除 30 天前的所有会话数据。

    sql
    sqlite> DELETE FROM sessions WHERE updated_at < strftime('%s', 'now', '-30 days') * 1000;

  3. 回收磁盘空间： 执行删除操作后，数据库文件大小可能不会立即减小。运行 VACUUM 命令可以重建数据库文件，回收磁盘空间。

    sql
    sqlite> VACUUM;

✅ 验证：

  • 备份：检查 ~/.opencode/ 目录，确认 .backup 文件已创建。
  • 清理：再次运行第 5 步的查询，确认旧会话已被删除。
  • 空间回收：VACUUM 命令没有输出，但数据库文件大小会变小。

⚠️ 常见错误： 永远不要在对数据库执行任何修改操作（如 DELETE）前忘记备份！ 这是一个毁灭性的操作。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 手动触发压缩：在特定场景下，你可以通过命令或快捷键手动压缩当前会话，例如在切换任务前。
  2. 使用 Task Session：在对话中，AI 可以自动创建子会话（Task Session）来处理子任务，如“搜索代码库中的所有 TODO”。这有助于保持主会话的上下文清晰。
  3. 理解会话层级：通过 parent_session_id 字段，你能在数据库中追溯会话的父子关系，形成一个树状结构。这让你能清晰地看到任务是如何分解的。

常见问题 (FAQ) ​

Q1: 会话没有保存怎么办？A: 请按顺序检查：

  1. 文件权限：确保 ~/.opencode/ 目录和 opencode.db 文件对当前用户有读写权限。
  2. 磁盘空间：检查磁盘是否已满。
  3. 数据库损坏：运行 sqlite3 ~/.opencode/opencode.db "PRAGMA integrity_check;" 命令检查数据库是否完整。

Q2: 自动压缩没有触发？A: 检查以下两点：

  1. autoCompact 是否在配置文件中设置为 true。
  2. 你的对话是否真的接近了模型的上下文窗口限制。某些模型可能有不同的限制。

Q3: 如何查看某个会话的 Token 消耗和成本？A: 在会话列表中，选中该会话，界面会显示相关信息。或者，你也可以直接查询 SQLite 数据库：

sql
sqlite> SELECT prompt_tokens, completion_tokens, cost FROM sessions WHERE id = '你的会话ID';

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 会话是核心：OpenCode 的每个对话都是一个独立的会话，包含消息、Token、成本等所有信息。
  2. 自动压缩是利器：开启 autoCompact 可以让你进行无限长的对话而不用担心上下文溢出。
  3. 数据库是基础：所有数据都存储在 ~/.opencode/opencode.db 这个 SQLite 文件中，你可以直接查询和管理它。
  4. 维护是习惯：定期备份、清理旧数据是保持 OpenCode 高效运行的好习惯。

© 2026 LowHow