OpenCode 完全指南：上下文管理与会话优化

OpenCode 的上下文窗口决定了 AI "能记住多少"。巧妙管理上下文——压缩对话、优化 Token、使用 compact 命令——是让 AI 持续高效工作的关键技巧。

上下文窗口基础

AI 模型的上下文窗口是有限的（通常 128K~1M tokens）。每次对话中，OpenCode 需要把：

对话历史
相关代码文件
系统提示词
工具调用结果

全部塞进这个窗口。一旦溢出，就需要"压缩"或"裁剪"。

上下文构成

┌─────────────────────────────┐
│ 系统提示词 (~2K tokens)      │
├─────────────────────────────┤
│ 项目文件 (变量, 取决于项目)   │
├─────────────────────────────┤
│ 对话历史 (逐渐增长)          │
├─────────────────────────────┤
│ 工具输出 (每次调用增加)       │
├─────────────────────────────┤
│ 可用空间 → 越来越少          │
└─────────────────────────────┘

compact 命令

当对话太长时，使用 /compact 压缩上下文：

> /compact

OpenCode 会把当前对话的要点总结成一段简洁的摘要，丢弃冗长的中间过程，释放上下文空间。

手动触发 vs 自动触发

// opencode.json
{
  "context": {
    "auto_compact": true,
    "compact_threshold": 0.8,
    "compact_keep": 10
  }
}

auto_compact：当上下文使用率超过阈值时自动压缩
compact_threshold：触发阈值（0-1，如 0.8 表示 80% 满时触发）
compact_keep：压缩后保留最近 N 轮对话

压缩策略

{
  "context": {
    "compaction_strategy": "summary"
  }
}

三种策略：

summary：AI 生成摘要替换历史（默认，信息密度最高）
truncate：丢弃最旧的对话（简单粗暴，可能丢上下文）
smart：保留重要信息（决策点、错误信息、已确认的约定）

上下文配置参数

// opencode.json
{
  "context": {
    "max_tokens": 32000,
    "max_lines": 20000,
    "max_files": 100,
    "max_file_size": 500000,
    "ignore_patterns": [
      "node_modules/",
      "dist/",
      ".next/",
      "*.lock",
      "*.map",
      ".git/"
    ],
    "include_summary": true,
    "truncation_strategy": "smart"
  }
}

参数详解

| 参数 | 作用 | 建议值 |
|------|------|--------|
| max_tokens | 发送给模型的最大 token 数 | 16000~64000 |
| max_lines | 最大代码行数 | 15000~30000 |
| max_files | 最大文件数 | 50~200 |
| max_file_size | 单个文件最大字节数 | 500000 (500KB) |
| ignore_patterns | 不扫描的文件模式 | 见上 |
| include_summary | 超限时附目录摘要 | true |
| truncation_strategy | 超限裁剪策略 | smart |

truncation_strategy 对比

| 策略 | 行为 | 适用场景 |
|------|------|----------|
| smart | 优先保留最近修改、关键路径文件 | 日常开发 |
| priority | 按文件优先级排序，丢弃低优 | 大型项目 |
| head | 保留文件头部（imports, 接口定义） | 了解项目结构 |
| tail | 保留文件尾部（当前编写位置） | 正在编辑文件 |

API 参数调优

// opencode.json
{
  "model": {
    "temperature": 0.2,
    "max_tokens": 8192,
    "top_p": 0.95,
    "frequency_penalty": 0.1,
    "presence_penalty": 0
  }
}

各参数影响

| 参数 | 范围 | 低值效果 | 高值效果 |
|------|------|---------|---------|
| temperature | 0~2 | 确定性输出，适合代码生成 | 创造性输出，适合头脑风暴 |
| max_tokens | 1~context_limit | 短回复，节省成本 | 长回复，适合生成完整文件 |
| top_p | 0~1 | 只选最可能的词 | 更多样化 |
| frequency_penalty | -2~2 | 允许重复 | 减少重复 |
| presence_penalty | -2~2 | 聚焦已有话题 | 鼓励新话题 |

场景推荐配置

// 代码生成（精确性优先）
{ "temperature": 0.1, "max_tokens": 8192 }

// 代码重构（需要一定创造力）
{ "temperature": 0.3, "max_tokens": 16384 }

// 头脑风暴/架构设计
{ "temperature": 0.7, "max_tokens": 32768 }

Token 成本优化

减少 Token 消耗的技巧

缩小文件范围：只看 src/services/ 而非整个项目

精确的 ignore_patterns：排除 *.generated.*, *.d.ts

用 AGENTS.md 代替每次贴规则：写好一次，每次复用

压缩后继续：长任务用 /compact 分段

分而治之：大需求拆成小任务，每个任务上下文更干净

监控 Token 用量

# 开启 Token 统计
codex --stats "..."

# 输出示例：
# Tokens: 4,230 prompt + 1,850 completion = 6,080 total
# Cost: $0.018 (GPT-4o)

在 opencode.json 中也可开启：

{
  "stats": true
}

实战技巧

长对话分阶段

阶段1: codex "理解项目结构，总结关键模块" → /compact
阶段2: codex "设计新功能的数据模型" → /compact
阶段3: codex "实现新功能的 API 路由" → /compact
阶段4: codex "编写测试"

上下文继承

# 在新对话开始时，注入上一轮的结论
codex "上一轮我们确定了使用策略模式重构 UserService。
请基于这个方案开始实现。"

文件优先级

通过 AGENTS.md 告诉 Codex 哪些文件最重要：

## 上下文优先级
当上下文不足时，优先保留以下文件：
1. src/types/ —— 类型定义决定一切
2. src/config/ —— 运行时配置
3. AGENTS.md —— 项目约定
其他文件不重要时可以不加载。

小结

上下文管理是 AI 编程的"内存管理"——配置好自动压缩、合理设置参数、善用 /compact，你就能让 OpenCode 在长任务中保持清醒和高效。