🦞 OpenClaw Token 消耗深度分析 — Agent 系统的 Token “原罪”

总成本 = Σ (input_tokens × 输入单价 + output_tokens × 输出单价)

┌─────────────────────────────────────────────────────────────────────────┐
│                    单次 LLM API 调用的 Token 构成                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────┐            │
│  │              Input Tokens (输入 Token)                    │            │
│  │                                                          │            │
│  │  ① System Prompt (系统提示词)          ~3,000-8,000 tokens │            │
│  │  ② Tool Definitions (工具定义)         ~2,000-5,000 tokens │            │
│  │  ③ Conversation History (对话历史)     0 ~ 200,000 tokens  │            │
│  │  ④ Memory Retrieval (记忆检索结果)     0 ~ 2,000 tokens    │            │
│  │  ⑤ Bootstrap Files (上下文文件)        0 ~ 10,000 tokens   │            │
│  │  ⑥ Current User Message (当前消息)     ~50-500 tokens      │            │
│  │                                                          │            │
│  └─────────────────────────────────────────────────────────┘            │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────┐            │
│  │             Output Tokens (输出 Token)                    │            │
│  │                                                          │            │
│  │  ⑦ Assistant Response (助手回复)       ~100-2,000 tokens   │            │
│  │  ⑧ Tool Calls (工具调用请求)           ~50-500 per call    │            │
│  │  ⑨ Thinking (推理过程)                 0 ~ 5,000 tokens    │            │
│  │                                                          │            │
│  └─────────────────────────────────────────────────────────┘            │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

典型 Token 分布（第 N 轮对话）:

Input:  ████████████████████████████████████████████  95%
Output: ██                                             5%

其中 Input 内部构成:
System Prompt:  ████                           ~15%
Tool Schema:    ███                            ~10%
History:        ████████████████████████████   ~65%
Current Msg:    █                              ~5%
Bootstrap:      ██                             ~5%

// 系统提示词的核心构建函数
export function buildAgentSystemPrompt(params: { ... }) {
  const lines = [
    "You are a personal assistant running inside OpenClaw.",  // 身份声明
    "",
    "## Tooling",           // 工具说明
    ...toolLines,           // 每个工具一行描述
    "",
    "## Tool Call Style",   // 工具调用风格
    ...                     // 叙述指南
    "",
    ...buildSafetySection(),        // 安全规则
    "## OpenClaw CLI Quick Reference", // CLI 参考
    ...skillsSection,               // Skills 系统
    ...memorySection,               // 记忆系统
    ...docsSection,                 // 文档参考
    ...                             // Messaging, Voice, Workspace 等
    "# Project Context",            // 项目上下文文件
    ...contextFiles,                // AGENTS.md, SOUL.md 等
    "## Silent Replies",            // 静默回复规则
    "## Heartbeats",                // 心跳检测
    "## Runtime",                   // 运行时信息
  ];
  return lines.filter(Boolean).join("\n");
}

// 上下文文件注入
if (contextFiles.length > 0) {
  lines.push("# Project Context", "");
  for (const file of contextFiles) {
    lines.push(`## ${file.path}`, "", file.content, "");
  }
}

export type PromptMode = "full" | "minimal" | "none";

// "none" 模式：极致节省
if (promptMode === "none") {
  return "You are a personal assistant running inside OpenClaw.";
}

{
  name: "memory_search",
  description: "Mandatory recall step: semantically search MEMORY.md + memory/*.md ...",
  parameters: Type.Object({
    query: Type.String(),
    maxResults: Type.Optional(Type.Number()),
    minScore: Type.Optional(Type.Number()),
  }),
}

┌──────────────────────────────────────────────────────────────────────────┐
│                     Agentic Loop 的 Token 放大效应                        │
└──────────────────────────────────────────────────────────────────────────┘

第 1 轮 API 调用:
  Input:  [System Prompt] + [Tool Defs] + [History] + [User Msg]
  Output: [Tool Call: read file "src/main.ts"]
  Token:  Input ~15,000 + Output ~100 = 15,100

第 2 轮 API 调用 (工具结果返回后):
  Input:  [System Prompt] + [Tool Defs] + [History] + [User Msg]
        + [Tool Call] + [Tool Result: file content ~500 lines]
  Output: [Tool Call: edit file "src/main.ts"]
  Token:  Input ~20,000 + Output ~200 = 20,200

第 3 轮 API 调用 (又一个工具结果):
  Input:  [System Prompt] + [Tool Defs] + [History] + [User Msg]
        + [Tool Call 1] + [Tool Result 1]
        + [Tool Call 2] + [Tool Result 2]
  Output: [Final Response: "文件已修改"]
  Token:  Input ~25,000 + Output ~100 = 25,100

总 Token 消耗: 15,100 + 20,200 + 25,100 = 60,400 tokens

Base = System Prompt + Tool Defs + History + User Message
ToolResult(i) = 第 i 个工具的结果大小

单次交互总 Input Token = Σ(i=1 to N+1) [Base + Σ(j=1 to i-1)(ToolCall(j) + ToolResult(j))]

简化为:
Total ≈ (N+1) × Base + N × (N+1) / 2 × AvgToolResult

会话开始时:
  History = 0 tokens

第 1 轮后:
  History = User(1) + Assistant(1) = ~300 tokens

第 5 轮后:
  History = 5 × (User + Assistant + ToolCalls + ToolResults) = ~5,000 tokens

第 20 轮后:
  History = 20 × (User + Assistant + ToolCalls + ToolResults) = ~20,000-50,000 tokens

第 50 轮后 (长会话):
  History = 50 × (...) = ~50,000-150,000 tokens  ← 可能接近上下文窗口上限！

export function limitHistoryTurns(
  messages: AgentMessage[],
  limit: number | undefined,
): AgentMessage[] {
  if (!limit || limit <= 0 || messages.length === 0) {
    return messages;
  }
  // 从后向前扫描，保留最后 N 个用户轮次
  let userCount = 0;
  let lastUserIndex = messages.length;
  for (let i = messages.length - 1; i >= 0; i--) {
    if (messages[i].role === "user") {
      userCount++;
      if (userCount > limit) {
        return messages.slice(lastUserIndex);
      }
      lastUserIndex = i;
    }
  }
  return messages;
}

// 通过渠道配置设置历史限制
config.channels.telegram.dmHistoryLimit = 50;   // 全局限制
config.channels.telegram.dms["user123"].historyLimit = 100; // 用户特定限制

// memory_search 工具定义
{
  name: "memory_search",
  description: "Mandatory recall step: semantically search MEMORY.md + memory/*.md ...",
  execute: async (_toolCallId, params) => {
    const results = await manager.search(query, { maxResults, minScore });
    return jsonResult({
      results,       // 搜索到的记忆片段
      provider,      // 提供商信息
      model,         // 模型信息
    });
  },
}

{
  name: "memory_get",
  description: "Safe snippet read from MEMORY.md, memory/*.md ... " +
    "use after memory_search to pull only the needed lines and keep context small.",
  parameters: {
    path: Type.String(),
    from: Type.Optional(Type.Number()),   // 起始行号
    lines: Type.Optional(Type.Number()),  // 读取行数
  },
}

┌──────────────────────────────────────────────────────────────────────────┐
│                  当前方案：两步记忆检索的 Token 消耗                        │
└──────────────────────────────────────────────────────────────────────────┘

第 1 轮 API 调用: LLM 决定调用 memory_search
  Input:  [System Prompt] + [Tool Defs] + [History] + [User Msg]
  Output: [Tool Call: memory_search("之前的决定")]
  Token:  Input ~15,000 + Output ~80 = ~15,080

      ↓ 执行 memory_search，返回 snippet + 行号

第 2 轮 API 调用: LLM 看到搜索结果，决定调用 memory_get
  Input:  [System Prompt] + [Tool Defs] + [History] + [User Msg]
        + [Tool Call 1] + [Tool Result 1: search results]
  Output: [Tool Call: memory_get("memory/2024-01.md", from=42, lines=10)]
  Token:  Input ~16,500 + Output ~100 = ~16,600

      ↓ 执行 memory_get，返回精准内容

第 3 轮 API 调用: LLM 拿到记忆内容，生成最终回复
  Input:  [System Prompt] + [Tool Defs] + [History] + [User Msg]
        + [Tool Call 1] + [Tool Result 1]
        + [Tool Call 2] + [Tool Result 2: memory content]
  Output: [Final Response]
  Token:  Input ~17,500 + Output ~300 = ~17,800

────────────────────────────
记忆检索总 Token 消耗: ~49,480 tokens
其中因多轮调用而重复发送的 Base 开销: ~15,000 × 2 = ~30,000 tokens (浪费)

// src/memory/manager.ts
const SNIPPET_MAX_CHARS = 700;  // ← 每个搜索结果的片段上限

// MemorySearchResult 的完整结构
export type MemorySearchResult = {
  path: string;        // 文件路径
  startLine: number;   // 起始行号
  endLine: number;     // 结束行号
  score: number;       // 相似度得分
  snippet: string;     // ← 已经包含了片段内容！最多 700 字符
  source: MemorySource; // 来源类型
};

// src/memory/manager.ts - readFile 方法
async readFile(params: {
  relPath: string;
  from?: number;
  lines?: number;
}): Promise<{ text: string; path: string }> {
  // ... 路径校验 ...
  const content = await fs.readFile(absPath, "utf-8");
  if (!params.from && !params.lines) {
    return { text: content, path: relPath };  // 返回整个文件
  }
  const lines = content.split("\n");
  const start = Math.max(1, params.from ?? 1);
  const count = Math.max(1, params.lines ?? lines.length);
  const slice = lines.slice(start - 1, start - 1 + count);
  return { text: slice.join("\n"), path: relPath };  // 返回指定行范围
}

// 优化后的 memory_search 工具（伪代码）
{
  name: "memory_search",
  description: "Search and retrieve memory content in one step...",
  execute: async (_toolCallId, params) => {
    const query = readStringParam(params, "query", { required: true });
    const { manager } = await getMemorySearchManager({ cfg, agentId });

    // Step 1: 向量搜索（与现在相同）
    const searchResults = await manager.search(query, { maxResults, minScore });

    // Step 2: ✨ 自动获取完整内容（替代 LLM 手动调用 memory_get）
    const enrichedResults = await Promise.all(
      searchResults.map(async (result) => {
        // 如果 snippet 已经足够完整，直接使用
        if (result.snippet.length < SNIPPET_MAX_CHARS * 0.9) {
          return { ...result, fullText: result.snippet };
        }
        // 否则读取完整的上下文行
        try {
          const full = await manager.readFile({
            relPath: result.path,
            from: result.startLine,
            lines: result.endLine - result.startLine + 1,
          });
          return { ...result, fullText: full.text };
        } catch {
          return { ...result, fullText: result.snippet };
        }
      })
    );

    return jsonResult({ results: enrichedResults, provider, model });
  },
}

┌──────────────────────────────────────────────────────────────────────────┐
│                  优化方案：单步记忆检索的 Token 消耗                        │
└──────────────────────────────────────────────────────────────────────────┘

第 1 轮 API 调用: LLM 决定调用 memory_search
  Input:  [System Prompt] + [Tool Defs] + [History] + [User Msg]
  Output: [Tool Call: memory_search("之前的决定")]
  Token:  Input ~15,000 + Output ~80 = ~15,080

      ↓ memory_search 内部自动完成搜索 + 内容获取

第 2 轮 API 调用: LLM 直接拿到完整记忆内容，生成最终回复
  Input:  [System Prompt] + [Tool Defs] + [History] + [User Msg]
        + [Tool Call] + [Tool Result: 完整记忆内容]
  Output: [Final Response]
  Token:  Input ~17,000 + Output ~300 = ~17,300

────────────────────────────
记忆检索总 Token 消耗: ~32,380 tokens
节省: ~49,480 - ~32,380 = ~17,100 tokens (节省 ~34.6%)

memory_search 返回 5 条结果
  → LLM 判断：只有第 2 条和第 4 条相关
  → 只对这 2 条调用 memory_get
  → 节省了读取另外 3 条的 Token

vs 单步方案：
  → 自动获取全部 5 条的完整内容
  → 可能有 3 条是不需要的

实际调用模式（根据系统提示词暗示的流程）：
  约 60% 的情况：memory_search 的 snippet 已足够 → 2 轮调用
  约 40% 的情况：需要 memory_get 获取更多内容 → 3 轮调用

// 当前值
const SNIPPET_MAX_CHARS = 700;    // 约 175 tokens/条结果

// 建议调整为
const SNIPPET_MAX_CHARS = 2000;   // 约 500 tokens/条结果

┌────────────────────────────────────────────────────────────────────┐
│                Compaction 的 Token 消耗结构                          │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  触发: 上下文接近/超过模型的 Context Window 限制                      │
│                                                                    │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  Step 1: 分块 (splitMessagesByTokenShare)                   │    │
│  │  将历史消息按 Token 均分为 2 份                               │    │
│  │  Token 消耗: 0 (纯计算)                                     │    │
│  └────────────────────────────────────────────────────────────┘    │
│                         │                                          │
│                         ▼                                          │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  Step 2: 分别摘要 (summarizeWithFallback)                   │    │
│  │  对每个分块调用 LLM 生成摘要                                 │    │
│  │  Token 消耗: 每块 Input ~50K + Output ~2K                   │    │
│  │  总计: 2 × (50K + 2K) = ~104K tokens ⚠️                    │    │
│  └────────────────────────────────────────────────────────────┘    │
│                         │                                          │
│                         ▼                                          │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  Step 3: 合并摘要 (MERGE_SUMMARIES_INSTRUCTIONS)            │    │
│  │  将分块摘要合并为最终摘要                                     │    │
│  │  Token 消耗: Input ~4K + Output ~2K = ~6K tokens            │    │
│  └────────────────────────────────────────────────────────────┘    │
│                         │                                          │
│                         ▼                                          │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  Step 4: 可能的降级处理 (pruneHistoryForContextShare)        │    │
│  │  如果新内容超过历史预算(50%)，裁剪旧消息再摘要               │    │
│  │  Token 消耗: 额外 ~50-100K tokens                           │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                    │
│  📊 单次 Compaction 总消耗: ~110K - 210K tokens                    │
│  💰 按 Claude Opus 4.5 计: ~$1.65 - $3.15                         │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

export async function summarizeInStages(params: {
  messages: AgentMessage[];
  model: NonNullable<ExtensionContext["model"]>;
  apiKey: string;
  signal: AbortSignal;
  reserveTokens: number;
  maxChunkTokens: number;
  contextWindow: number;
  ...
}): Promise<string> {
  // 1. 分块
  const splits = splitMessagesByTokenShare(messages, parts);

  // 2. 对每个分块生成摘要（每个都是一次独立的 API 调用！）
  for (const chunk of splits) {
    partialSummaries.push(
      await summarizeWithFallback({ ...params, messages: chunk })
    );
  }

  // 3. 合并摘要（又一次 API 调用！）
  return summarizeWithFallback({
    ...params,
    messages: summaryMessages,
    customInstructions: mergeInstructions,
  });
}

// src/agents/pi-extensions/compaction-safeguard.ts
api.on("session_before_compact", async (event, ctx) => {
  // 可能需要先摘要被裁剪的消息
  if (pruned.droppedMessagesList.length > 0) {
    droppedSummary = await summarizeInStages({...});  // 额外的 API 调用
  }
  // 主摘要
  const historySummary = await summarizeInStages({...});  // 又一轮 API 调用
  // 如果是分割轮次，还要摘要前缀
  if (preparation.isSplitTurn) {
    const prefixSummary = await summarizeInStages({...});  // 再一轮！
  }
});

单次交互总 Token = (N+1) × Base + ToolOverhead + OutputTokens

其中:
  Base = SystemPrompt + ToolDefs + History + BootstrapFiles
  N = 工具调用轮数
  ToolOverhead = Σ(i=1 to N) [ToolCall(i) + ToolResult(i)] × 重复发送因子
  OutputTokens = FinalReply + Σ(ToolCallOutputs)

System Prompt:    3,000 tokens
Tool Definitions: 3,500 tokens
History (5 轮):   3,000 tokens
User Message:       100 tokens
────────────────────────────
Input Total:      9,600 tokens
Output:             200 tokens
────────────────────────────
💰 总计:          ~9,800 tokens (~$0.16)

API Call 1: (LLM 决定读文件)
  Input:  9,600 tokens
  Output:   100 tokens (tool call: read)

API Call 2: (读取结果返回，LLM 决定编辑)
  Input:  9,600 + 100 + 3,000 = 12,700 tokens
  Output:   300 tokens (tool call: edit)

API Call 3: (编辑结果返回，LLM 生成回复)
  Input:  12,700 + 300 + 200 = 13,200 tokens
  Output:   200 tokens (final reply)

────────────────────────────
Input Total:  35,500 tokens
Output Total:    600 tokens
────────────────────────────
💰 总计: ~36,100 tokens (~$0.58)

Base:                 30,000 tokens (含 20K 历史)
工具结果平均大小:       3,000 tokens/轮
工具调用次数:          10 轮

Input: 11 × 30,000 + 10×11/2 × 3,000 = 330,000 + 165,000 = 495,000 tokens
Output: ~3,000 tokens

────────────────────────────
💰 总计: ~498,000 tokens (~$7.72)

轮次 1-10:   History 小，平均每轮 ~30K tokens → ~300K
轮次 11-20:  History 增长，平均每轮 ~60K tokens → ~600K
轮次 21-30:  Context Pruning 开始生效，平均每轮 ~80K tokens → ~800K
轮次 31-40:  Compaction 触发 2-3 次，额外 ~500K tokens → ~1,300K
轮次 41-50:  稳态运行，平均每轮 ~70K tokens → ~700K

50 轮会话总消耗: ~3.7M tokens
💰 按 Claude Opus 4.5: ~$55 (无缓存) 或 ~$15 (高缓存命中率)

const CHARS_PER_TOKEN_ESTIMATE = 4;        // 每个 Token 约 4 个字符
const IMAGE_CHAR_ESTIMATE = 8_000;         // 图片按 8000 字符估算

export const SAFETY_MARGIN = 1.2;  // 20% 安全边界，补偿估算不精确

export function estimateMessagesTokens(messages: AgentMessage[]): number {
  return messages.reduce((sum, message) => sum + estimateTokens(message), 0);
}

function estimateMessageChars(message: AgentMessage): number {
  if (message.role === "user") {
    // 文本: 直接取字符长度
    // 图片: 每张 8,000 字符
  }
  if (message.role === "assistant") {
    // text: 字符长度
    // thinking: 字符长度
    // toolCall: JSON.stringify(arguments).length
  }
  if (message.role === "toolResult") {
    // text: 字符长度
    // image: 每张 8,000 字符
  }
  return 256;  // 未知类型的默认值
}

export type UsageLike = {
  // Anthropic 风格
  input?: number;
  output?: number;
  cacheRead?: number;
  cacheWrite?: number;

  // OpenAI 风格
  inputTokens?: number;
  outputTokens?: number;
  promptTokens?: number;
  completionTokens?: number;

  // API 响应风格 (snake_case)
  input_tokens?: number;
  output_tokens?: number;
  cache_read_input_tokens?: number;
  cache_creation_input_tokens?: number;
  total_tokens?: number;
};

export type NormalizedUsage = {
  input?: number;      // 输入 Token 数
  output?: number;     // 输出 Token 数
  cacheRead?: number;  // 缓存读取 Token 数
  cacheWrite?: number; // 缓存写入 Token 数
  total?: number;      // 总 Token 数
};

export function derivePromptTokens(usage?: {
  input?: number;
  cacheRead?: number;
  cacheWrite?: number;
}): number | undefined {
  const sum = (usage.input ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
  return sum > 0 ? sum : undefined;
}

export type CacheTraceStage =
  | "session:loaded"     // 会话加载
  | "session:sanitized"  // 会话清理后
  | "session:limited"    // 历史限制后
  | "prompt:before"      // 发送前
  | "prompt:images"      // 图片处理
  | "stream:context"     // 流式上下文
  | "session:after";     // 会话结束后

# 通过环境变量启用
OPENCLAW_CACHE_TRACE=1

# 或通过配置文件
diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl"
    includeMessages: true
    includePrompt: true
    includeSystem: true

export const DEFAULT_CONTEXT_PRUNING_SETTINGS: EffectiveContextPruningSettings = {
  mode: "cache-ttl",
  ttlMs: 5 * 60 * 1000,           // 5 分钟 TTL
  keepLastAssistants: 3,           // 保护最后 3 个 assistant 回复
  softTrimRatio: 0.3,             // 占 30% 上下文时触发软裁剪
  hardClearRatio: 0.5,            // 占 50% 上下文时触发硬清除
  minPrunableToolChars: 50_000,   // 最小可裁剪字符数
  softTrim: {
    maxChars: 4_000,              // 超过 4000 字符触发
    headChars: 1_500,             // 保留开头 1500 字符
    tailChars: 1_500,             // 保留结尾 1500 字符
  },
  hardClear: {
    enabled: true,
    placeholder: "[Old tool result content cleared]",
  },
};

上下文占用比例 (ratio = totalChars / charWindow)
              │
              ▼
   ratio < 0.3 ──────────────→ 不裁剪 (Token 充裕)
              │
              ▼
  0.3 ≤ ratio < 0.5 ─────────→ 软裁剪 (Soft Trim)
              │                  • 保留工具结果的头 1500 + 尾 1500 字符
              │                  • 中间内容标记为 "..."
              │                  • 典型节省: 50-80% 单条工具结果
              ▼
    ratio ≥ 0.5 ─────────────→ 硬清除 (Hard Clear)
                                 • 替换为 "[Old tool result content cleared]"
                                 • 典型节省: 95%+ 单条工具结果

保护规则:
  ✅ 保护最后 3 个 assistant 回复关联的工具结果
  ✅ 保护首个 user 消息之前的所有内容 (bootstrap files)
  ✅ 跳过包含图片的工具结果

api.on("session_before_compact", async (event, ctx) => {
  // 1. 计算自适应分块比例
  const adaptiveRatio = computeAdaptiveChunkRatio(allMessages, contextWindowTokens);
  // 当消息较大时，使用更小的分块避免超出模型限制
  // 范围: 0.15 (MIN_CHUNK_RATIO) ~ 0.4 (BASE_CHUNK_RATIO)

  // 2. 裁剪超量历史
  if (newContentTokens > maxHistoryTokens) {
    const pruned = pruneHistoryForContextShare({
      messages: messagesToSummarize,
      maxContextTokens: contextWindowTokens,
      maxHistoryShare: 0.5,  // 历史最多占 50%
    });
  }

  // 3. 分阶段摘要
  const historySummary = await summarizeInStages({...});

  // 4. 附加文件操作和工具失败信息
  summary += toolFailureSection;
  summary += fileOpsSummary;
});

BASE_CHUNK_RATIO = 0.4;     // 每个分块最多占 40% 上下文 = 80K tokens (200K 窗口)
MIN_CHUNK_RATIO = 0.15;     // 最小分块 = 30K tokens
SAFETY_MARGIN = 1.2;        // 20% 安全边界
maxHistoryShare = 0.5;       // 历史压缩后最多占 50% 上下文 = 100K tokens

CONTEXT_WINDOW_HARD_MIN_TOKENS = 16_000;    // 低于此值直接拒绝使用该模型
CONTEXT_WINDOW_WARN_BELOW_TOKENS = 32_000;  // 低于此值发出警告

1. modelsConfig (用户在配置中指定的上下文大小)
2. model metadata (模型自带的上下文大小)
3. agentContextTokens (Agent 配置的上下文上限)
4. default (默认值: 200,000)

export function resolveContextWindowInfo(params: {
  cfg, provider, modelId, modelContextWindow, defaultTokens
}): ContextWindowInfo {
  // 1. 优先使用用户配置的 contextWindow
  const fromModelsConfig = findModelConfig(cfg, provider, modelId)?.contextWindow;
  // 2. 其次使用模型元数据
  const fromModel = params.modelContextWindow;
  // 3. 如果 agentContextTokens 更小，使用它作为上限
  const capTokens = cfg?.agents?.defaults?.contextTokens;
  if (capTokens && capTokens < baseInfo.tokens) {
    return { tokens: capTokens, source: "agentContextTokens" };
  }
}

type CacheRetention = "none" | "short" | "long";

function resolveCacheRetention(
  extraParams: Record<string, unknown> | undefined,
  provider: string,
): CacheRetention | undefined {
  if (provider !== "anthropic") return undefined;  // 仅 Anthropic 支持

  // 新配置: cacheRetention
  if (newVal === "short" || newVal === "long") return newVal;

  // 旧配置兼容: cacheControlTtl
  if (legacy === "5m") return "short";   // 5 分钟缓存
  if (legacy === "1h") return "long";    // 1 小时缓存
}

无缓存:
  200K input tokens × $15/1M = $3.00/次

缓存命中 (假设 90% 命中率):
  20K 新 tokens × $15/1M + 180K 缓存 tokens × $1.5/1M = $0.30 + $0.27 = $0.57/次

节省: $3.00 - $0.57 = $2.43/次 (81% 成本节省!)

export function limitHistoryTurns(
  messages: AgentMessage[],
  limit: number | undefined,
): AgentMessage[] {
  // 保留最后 N 个用户轮次（及其关联的 assistant 回复和工具调用）
  // 超出的部分直接丢弃（不生成摘要）
}

当前: 每次发送 ~20 个工具定义 = ~4,000 tokens
优化: 根据意图预判只发送 5-8 个 = ~1,500 tokens
节省: ~2,500 tokens/次

LLM(完整上下文) → 回复

┌─────────────────────────────────────────────────────────────────────────┐
│                   每轮 API 调用的固定 "Base 成本"                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   System Prompt (系统指令)        ~3,000-8,000 tokens    ← 每次都发     │
│   Tool Definitions (工具定义)     ~3,000-5,000 tokens    ← 每次都发     │
│   Bootstrap Files (上下文文件)    ~2,000-5,000 tokens    ← 每次都发     │
│   对话历史 (所有历史消息)          ~1,000-∞ tokens        ← 持续增长     │
│                                                                         │
│   合计 Base 成本: ~10,000-20,000+ tokens / 轮                           │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│            普通 ChatBot vs Agent 系统的 Token 消耗对比                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  普通 ChatBot:                                                          │
│    用户问 → LLM 答                                                      │
│    = 1 轮 API 调用                                                      │
│    ≈ 15,000 tokens                                                      │
│                                                                         │
│  Agent 系统:                                                            │
│    用户问 → LLM 思考 → 调工具A → 看结果 → 调工具B → 看结果 → 最终回答     │
│    = 3-5 轮 API 调用                                                    │
│    ≈ 50,000-80,000 tokens                                               │
│                                                                         │
│  复杂 Agent 任务:                                                       │
│    搜索记忆 → 读取文件 → 分析内容 → 搜索网页 → 综合推理 → 回答            │
│    = 5-10 轮 API 调用                                                   │
│    ≈ 100,000-200,000 tokens                                             │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

第 1 轮: Base                              = 15,000 tokens
第 2 轮: Base + 第1轮结果                    = 16,500 tokens
第 3 轮: Base + 第1轮结果 + 第2轮结果         = 18,000 tokens
第 4 轮: Base + 第1轮 + 第2轮 + 第3轮结果     = 19,500 tokens
第 5 轮: Base + 第1轮 + 第2轮 + 第3轮 + 第4轮  = 21,000 tokens
─────────────────────────────────────────────────
5 轮总消耗: 90,000 tokens（而非 5 × 15,000 = 75,000）

┌─────────────────────────────────────────────────────────────────────────┐
│                    对话历史的滚雪球增长曲线                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Token ▲                                                                │
│  消耗  │                                              ╱ 无优化          │
│        │                                           ╱                    │
│  100K  │                                        ╱                       │
│        │                                     ╱                          │
│   80K  │                                  ╱                             │
│        │                               ╱     ╱ 有 Compaction           │
│   60K  │                            ╱     ╱                             │
│        │                         ╱     ╱                                │
│   40K  │                      ╱     ╱                                   │
│        │                   ╱     ╱                                      │
│   20K  │                ╱  ╱╱                                           │
│        │          ╱╱╱╱╱                                                 │
│   15K  │───╱╱╱╱                                                         │
│        └──────────────────────────────────────────────────▶ 对话轮次     │
│            1    5    10   15   20   25   30   35   40                   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│               Agent 框架 Token 优化能力对比                               │
├──────────────┬──────────┬──────────┬──────────┬──────────┬──────────────┤
│   优化手段    │ OpenClaw │ LangChain│  AutoGPT │  CrewAI  │ 简单 Agent   │
├──────────────┼──────────┼──────────┼──────────┼──────────┼──────────────┤
│ Prompt Cache │   ✅     │   ⚠️    │    ❌    │   ❌     │     ❌       │
│ Compaction   │   ✅     │   ⚠️    │    ⚠️   │   ❌     │     ❌       │
│ 上下文裁剪    │   ✅     │   ⚠️    │    ⚠️   │   ⚠️    │     ❌       │
│ 工具结果压缩  │   ✅     │   ❌    │    ❌    │   ❌     │     ❌       │
│ 历史轮次限制  │   ✅     │   ✅    │    ⚠️   │   ✅     │     ❌       │
│ Token 追踪   │   ✅     │   ✅    │    ⚠️   │   ⚠️    │     ❌       │
│ 记忆 snippet │   ✅     │   ❌    │    ❌    │   ❌     │     ❌       │
├──────────────┼──────────┼──────────┼──────────┼──────────┼──────────────┤
│ 综合优化程度  │  ⭐⭐⭐⭐ │  ⭐⭐⭐  │  ⭐⭐    │  ⭐⭐    │    ⭐        │
└──────────────┴──────────┴──────────┴──────────┴──────────┴──────────────┘

✅ = 已实现且较完善   ⚠️ = 部分实现或较简单   ❌ = 未实现

当前:  Client → [完整上下文 50K tokens] → LLM API → 回复
未来:  Client → [增量消息 200 tokens]   → LLM API(session_id) → 回复
                                          ↑ 服务端维持状态

当前:  每轮发送 [System + Tools + 全部历史 + 新消息]  = 50K tokens
未来:  首轮发送 [System + Tools + 首条消息]            = 15K tokens
       后续发送 [session_ref + 增量 diff]              = 500 tokens

2023:  GPT-4     输入 $30/1M tokens
2024:  GPT-4o    输入 $5/1M tokens      ← 6x 降价
2024:  Claude 3.5 Sonnet 输入 $3/1M tokens
2025:  预期进一步降低...

┌─────────────────────────────────────────────────────────────────────────┐
│                     Token 消耗从高到低排序                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  🔴 超高消耗 (>100K tokens/次)                                           │
│     • Compaction 压缩 (多次 LLM 调用)                                    │
│     • 长会话的累积历史 (未压缩时)                                         │
│                                                                         │
│  🟠 高消耗 (10K-100K tokens/次)                                          │
│     • Agentic Loop 多轮调用 (累积效应)                                    │
│     • 大文件读取/网页抓取 (工具结果)                                      │
│                                                                         │
│  🟡 中等消耗 (1K-10K tokens/次)                                          │
│     • System Prompt (每次调用)                                            │
│     • Tool Definitions (每次调用)                                        │
│     • Bootstrap Files (AGENTS.md 等)                                     │
│                                                                         │
│  🟢 低消耗 (<1K tokens/次)                                               │
│     • 用户消息                                                           │
│     • 记忆搜索结果                                                       │
│     • 助手最终回复                                                       │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘