AgentScope Gemini 用量修复

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install agentscope-gemini-usage-fix
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 agentscope-gemini-usage-fix。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

AgentScope Gemini 用量修复记录了 GeminiChatModel 中一个已知的用量提取错误：当 cached_content_token_count 存在但值为 None 时，模型会将该值传入 ChatUsage.cache_input_tokens；此字段要求整数，因此会引发 Pydantic ValidationError。
此技能提供一个小型运行时猴子补丁，在缓存 Token 数量缺失导致验证失败前将其转换为 0，并提供上游的一行修正方案。对于使用 AgentScope 和 Gemini 的 Openclaw Skills 开发者，它提供了一个针对性的临时方案，可在库修复可用前使用。

应用场景

GeminiChatModel
调用引发 Pydantic
ValidationError
，错误提及
cache_input_tokens
。
Gemini 用量元数据包含
cached_content_token_count=None
。
等待升级到包含上游修复的版本期间，你需要一个临时运行时方案。
你正在诊断 AgentScope Gemini Token 用量提取行为。

工作原理

导入 GeminiChatModel，并保留其原始 _extract_usage 方法的引用。
将 _extract_usage 替换为一个包装函数；如果用量元数据缺失，则返回 None。
如果元数据可用，则调用原始提取方法。
如果生成的用量对象的 cache_input_tokens 为 None，则将其设为 0。
在调用 Gemini 模型之前，将包装函数赋给 GeminiChatModel._extract_usage，使得用量验证接收到整数。

配置指南

设置所需的 Google API 密钥，并确保环境中有 Python 3 和 AgentScope。在应用启动期间、创建或使用 Gemini 模型调用之前应用此补丁：
export GOOGLE_API_KEY="your-google-api-key"
from agentscope.model._gemini._model import GeminiChatModel
_original = GeminiChatModel._extract_usage
def _patched_extract_usage(self, usage_metadata, start_datetime):
if not usage_metadata:
return None
usage = _original(self, usage_metadata, start_datetime)
if usage and getattr(usage, "cache_input_tokens", None) is None:
usage.cache_input_tokens = 0
return usage
GeminiChatModel._extract_usage = _patched_extract_usage
此技能未指定软件包安装命令，也未固定 AgentScope 版本。上游的一行修复是在赋值给 cache_input_tokens 时使用 getattr(usage_metadata, "cached_content_token_count", 0) or 0。
AgentScope Gemini 用量修复 数据架构与分类体系
此技能不会创建文件、持久化数据，也不会为应用记录定义元数据分类体系。其配置和运行时行为如下：
项目 详情
必需的环境变量 GOOGLE_API_KEY — Google Generative AI API 密钥
必需的可执行文件 python3
修补的组件 GeminiChatModel._extract_usage
受影响的用量字段 ChatUsage.cache_input_tokens
备用值 提取出的缓存 Token 数量为 None 时使用整数 0
参考 AgentScope issue #3077

高级特性

包装原始方法，而不是替换整个用量提取实现。
用量元数据缺失时返回
None
，而不调用原始方法。
None
缓存 Token 值规范化为 0 ，以满足整数验证要求。
指出上游的一行修正；当该修正并入已安装的 AgentScope 版本后，可用它替代猴子补丁。
针对特定的
GeminiChatModel
用量提取路径；不涉及更广泛的模型、智能体或自动化功能。

name: agentscope-gemini-usage-fix description: Work around a Gemini usage normalization bug in AgentScope where cached_content_token_count=None causes Usage validation to fail. Use this whenever the user uses GeminiChatModel and sees ValidationError on cache_input_tokens. version: 0.1.0