OpenClaw Tokenjuice 插件详解为 exec/bash 工具结果自动压缩降噪【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawTokenjuice 是 OpenClaw 的可选外部插件在exec、bash等命令工具执行完毕后对返回的tool_result进行压缩与结构化整理再交还给正在运行的 Agent 会话。本文以 docs/tools/tokenjuice.md 为主线结合 extensions/tokenjuice 的源码与测试讲解它的作用边界、安装启用方式、压缩策略、验证方法与关闭流程帮助你判断是否应该为长会话场景引入它。一、Tokenjuice 是什么只改结果不改执行tokenjuice是一个可选的外部插件其核心职责是在exec和bash工具的命令已经运行完之后压缩它们嘈杂的输出结果。需要特别强调的是它的作用边界——它改变的是返回的tool_result而不是命令本身不重写 shell 输入不重新执行命令不改变退出码exit code。换句话说Tokenjuice 是一个纯粹的“结果后处理”插件位于命令执行的语义之外因此不会带来二次执行或语义漂移的风险。从当前仓库的实际代码看它的作用范围目前覆盖两类运行环境OpenClaw embedded runs内嵌运行Codex app-server harness 中的 OpenClaw dynamic toolsOpenClaw 动态工具。插件通过挂载 OpenClaw 的tool-result middleware工具结果中间件在结果回流到活跃 harness 会话之前完成裁剪。插件入口 extensions/tokenjuice/index.ts 使用definePluginEntry注册并调用api.registerAgentToolResultMiddleware(createTokenjuiceAgentToolResultMiddleware(), { runtimes: [openclaw, codex], });也就是说中间件同时注册到了openclaw与codex两个运行时与文档中“OpenClaw embedded runs Codex app-server harness”的适用范围完全一致extensions/tokenjuice/manifest.test.ts 也专门断言了 manifest 中contracts.agentToolResultMiddleware声明为[openclaw, codex]。二、安装与启用插件2.1 安装一次openclaw plugins install clawhub:openclaw/tokenjuice从 extensions/tokenjuice/package.json 可以看到该插件同时发布到 ClawHub 与 npmClawHub 规格clawhub:openclaw/tokenjuicenpm 规格openclaw/tokenjuice默认安装源npm最低宿主版本2026.5.28如果你更习惯从 npm 安装也可以使用openclaw plugins install openclaw/tokenjuiceextensions/tokenjuice/README.md 推荐在安装或更新插件后重启 Gateway。仓库内openclaw/tokenjuice当前版本为2026.9.2其运行依赖为tokenjuice0.8.1peerDependencies 要求宿主openclaw 2026.9.2插件 API 兼容版本同样为2026.9.2。2.2 启用插件openclaw config set plugins.entries.tokenjuice.enabled true等效命令openclaw plugins enable tokenjuice如果你更喜欢直接编辑配置文件可以在配置中加入如下 JSON5 片段{ plugins: { entries: { tokenjuice: { enabled: true, }, }, }, }值得注意的是extensions/tokenjuice/openclaw.plugin.json 中的configSchema为空对象additionalProperties: false且没有任何属性意味着该插件没有暴露额外的插件级配置项开箱即用启用与否就是它唯一的开关。同时该 manifest 中activation.onStartup为false插件不需要在启动时主动激活而是按需注册中间件。另外仓库测试 extensions/tokenjuice/index.test.ts 断言 manifest 中不存在enabledByDefault字段从测试与配置结构可以确认Tokenjuice 默认不启用是一个明确的 opt-in 插件。三、Tokenjuice 会改变什么、保留什么文档明确了四条行为准则压缩嘈杂的exec/bash结果在结果回灌会话之前完成压缩保持原始命令执行不变命令本身、执行次数、退出码都不受影响应用 safe-inventory 策略精确的文件内容读取保持原样raw独立的仓库清单类命令可以压缩不安全的混合命令序列保持原样保持 opt-in关闭插件即可在所有场景恢复逐字verbatim输出。“safe-inventory”策略本质是一套保守的压缩判定只有当输出可以被判定为“安全的库存/清单类信息”时才压缩凡是可能涉及完整文件内容读取、或者混入了可能产生副作用的命令序列都选择保留原文宁可牺牲压缩率也不冒险丢失信息。这保证了压缩不会掩盖错误、不会截断关键内容。四、源码级原理中间件如何压缩结果4.1 中间件管线核心实现位于 extensions/tokenjuice/tool-result-middleware.ts。createTokenjuiceAgentToolResultMiddleware()会通过createTokenjuiceOpenClawEmbeddedExtension()由 extensions/tokenjuice/runtime-api.ts 从tokenjuice/openclaw重新导出建立与 tokenjuice 库的连接监听tool_result事件收集 reducer 处理器在中间件执行时依次调用每个处理器将返回的content与details合并回当前结果若结果没有变化则返回undefined不产生无意义的新结果否则返回{ result: current }。工作目录cwd的解析也有明确的优先级优先取事件自带的cwd否则取args.workdir最后回退到process.cwd()。4.2 状态与退出码的归一化为了让 tokenjuice 能正确判断压缩后的呈现方式中间件在把事件交给处理器之前会先做一次normalizeDetailsextensions/tokenjuice/tool-result-middleware.ts仅对exec/bash且带非空command参数的事件生效删除重复的aggregated原始副本源码注释明确指出tokenjuice 在aggregated缺失时会读取文本内容随后再把 details 合并回响应如果保留重复的原始副本压缩结果可能超过宿主限制合成规范的status与exitCode如果已有非空status字符串则视为规范值直接保留否则根据isError、ok、success、timedOut、error、exitCode综合推导出failed/completed状态并给出合理的exitCode有合法数值则保留原值否则失败为 1、成功为 0。这部分行为在 extensions/tokenjuice/index.test.ts 有直接验证当 bash 只提供truncation、fullOutputPath等元数据时中间件会补上status: completed与exitCode: 0同时不携带aggregated。测试还逐一覆盖了exitCode: 7、success: false、ok: false、timedOut: true、error: ...等失败推导路径extensions/tokenjuice/index.test.ts确认这些场景都会被归一化为status: failed。4.3 压缩结果受宿主上限保护测试 extensions/tokenjuice/index.test.ts 演示了一个 120,000 字符的原始输出在中间件管线中替换为 compacted并且details携带tokenjuice: { compacted: true }标记且保持在中间件 details 限制之内。这说明压缩后的结果仍然会遵守宿主对details体积的限制不会因为压缩逻辑本身引入超限负载。五、验证 Tokenjuice 是否生效按文档给出的步骤操作即可启用插件见上文 2.2 节启动一个可以调用exec的会话运行一条嘈杂命令例如git status检查返回的 tool result 是否比原始 shell 输出更短、更结构化。如果返回结果出现了结构化的压缩标记例如details中带有tokenjuice.compacted这样的元信息且原始命令的退出码与执行语义保持一致即可确认插件处于生效状态。六、关闭插件当不需要压缩、希望所有场景都拿到逐字输出时两种方式任选其一openclaw config set plugins.entries.tokenjuice.enabled false或者openclaw plugins disable tokenjuice关闭后exec/bash的工具结果将恢复原始形式不再经过 tokenjuice 的 reducer 处理这也再次印证了它“opt-in、可逆”的设计定位。七、总结与相关文档Tokenjuice 解决的是 Agent 长会话中一个非常具体的痛点exec/bash的原始输出往往充满噪音、占用大量上下文窗口。它通过 tool-result 中间件在结果回灌前完成压缩同时严守“不改命令、不重跑、不改退出码”的边界并以 safe-inventory 策略保护文件内容读取与不安全命令序列做到在节省 token 与上下文空间的同时不牺牲正确性。对希望控制上下文膨胀、让 Agent 更专注于结构化信息的用户来说这是一个低成本、可随时启停的优化手段。围绕该主题可以继续阅读仓库内相关文档Exec 工具文档Thinking levels 文档Context engine 概念文档插件完整实现与测试见 extensions/tokenjuice包括入口 index.ts、中间件实现 tool-result-middleware.ts、运行时契约 runtime-api.ts 以及行为测试 index.test.ts。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenClaw Tokenjuice 插件详解：为 exec/bash 工具结果自动压缩降噪
OpenClaw Tokenjuice 插件详解为 exec/bash 工具结果自动压缩降噪【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawTokenjuice 是 OpenClaw 的可选外部插件在exec、bash等命令工具执行完毕后对返回的tool_result进行压缩与结构化整理再交还给正在运行的 Agent 会话。本文以 docs/tools/tokenjuice.md 为主线结合 extensions/tokenjuice 的源码与测试讲解它的作用边界、安装启用方式、压缩策略、验证方法与关闭流程帮助你判断是否应该为长会话场景引入它。一、Tokenjuice 是什么只改结果不改执行tokenjuice是一个可选的外部插件其核心职责是在exec和bash工具的命令已经运行完之后压缩它们嘈杂的输出结果。需要特别强调的是它的作用边界——它改变的是返回的tool_result而不是命令本身不重写 shell 输入不重新执行命令不改变退出码exit code。换句话说Tokenjuice 是一个纯粹的“结果后处理”插件位于命令执行的语义之外因此不会带来二次执行或语义漂移的风险。从当前仓库的实际代码看它的作用范围目前覆盖两类运行环境OpenClaw embedded runs内嵌运行Codex app-server harness 中的 OpenClaw dynamic toolsOpenClaw 动态工具。插件通过挂载 OpenClaw 的tool-result middleware工具结果中间件在结果回流到活跃 harness 会话之前完成裁剪。插件入口 extensions/tokenjuice/index.ts 使用definePluginEntry注册并调用api.registerAgentToolResultMiddleware(createTokenjuiceAgentToolResultMiddleware(), { runtimes: [openclaw, codex], });也就是说中间件同时注册到了openclaw与codex两个运行时与文档中“OpenClaw embedded runs Codex app-server harness”的适用范围完全一致extensions/tokenjuice/manifest.test.ts 也专门断言了 manifest 中contracts.agentToolResultMiddleware声明为[openclaw, codex]。二、安装与启用插件2.1 安装一次openclaw plugins install clawhub:openclaw/tokenjuice从 extensions/tokenjuice/package.json 可以看到该插件同时发布到 ClawHub 与 npmClawHub 规格clawhub:openclaw/tokenjuicenpm 规格openclaw/tokenjuice默认安装源npm最低宿主版本2026.5.28如果你更习惯从 npm 安装也可以使用openclaw plugins install openclaw/tokenjuiceextensions/tokenjuice/README.md 推荐在安装或更新插件后重启 Gateway。仓库内openclaw/tokenjuice当前版本为2026.9.2其运行依赖为tokenjuice0.8.1peerDependencies 要求宿主openclaw 2026.9.2插件 API 兼容版本同样为2026.9.2。2.2 启用插件openclaw config set plugins.entries.tokenjuice.enabled true等效命令openclaw plugins enable tokenjuice如果你更喜欢直接编辑配置文件可以在配置中加入如下 JSON5 片段{ plugins: { entries: { tokenjuice: { enabled: true, }, }, }, }值得注意的是extensions/tokenjuice/openclaw.plugin.json 中的configSchema为空对象additionalProperties: false且没有任何属性意味着该插件没有暴露额外的插件级配置项开箱即用启用与否就是它唯一的开关。同时该 manifest 中activation.onStartup为false插件不需要在启动时主动激活而是按需注册中间件。另外仓库测试 extensions/tokenjuice/index.test.ts 断言 manifest 中不存在enabledByDefault字段从测试与配置结构可以确认Tokenjuice 默认不启用是一个明确的 opt-in 插件。三、Tokenjuice 会改变什么、保留什么文档明确了四条行为准则压缩嘈杂的exec/bash结果在结果回灌会话之前完成压缩保持原始命令执行不变命令本身、执行次数、退出码都不受影响应用 safe-inventory 策略精确的文件内容读取保持原样raw独立的仓库清单类命令可以压缩不安全的混合命令序列保持原样保持 opt-in关闭插件即可在所有场景恢复逐字verbatim输出。“safe-inventory”策略本质是一套保守的压缩判定只有当输出可以被判定为“安全的库存/清单类信息”时才压缩凡是可能涉及完整文件内容读取、或者混入了可能产生副作用的命令序列都选择保留原文宁可牺牲压缩率也不冒险丢失信息。这保证了压缩不会掩盖错误、不会截断关键内容。四、源码级原理中间件如何压缩结果4.1 中间件管线核心实现位于 extensions/tokenjuice/tool-result-middleware.ts。createTokenjuiceAgentToolResultMiddleware()会通过createTokenjuiceOpenClawEmbeddedExtension()由 extensions/tokenjuice/runtime-api.ts 从tokenjuice/openclaw重新导出建立与 tokenjuice 库的连接监听tool_result事件收集 reducer 处理器在中间件执行时依次调用每个处理器将返回的content与details合并回当前结果若结果没有变化则返回undefined不产生无意义的新结果否则返回{ result: current }。工作目录cwd的解析也有明确的优先级优先取事件自带的cwd否则取args.workdir最后回退到process.cwd()。4.2 状态与退出码的归一化为了让 tokenjuice 能正确判断压缩后的呈现方式中间件在把事件交给处理器之前会先做一次normalizeDetailsextensions/tokenjuice/tool-result-middleware.ts仅对exec/bash且带非空command参数的事件生效删除重复的aggregated原始副本源码注释明确指出tokenjuice 在aggregated缺失时会读取文本内容随后再把 details 合并回响应如果保留重复的原始副本压缩结果可能超过宿主限制合成规范的status与exitCode如果已有非空status字符串则视为规范值直接保留否则根据isError、ok、success、timedOut、error、exitCode综合推导出failed/completed状态并给出合理的exitCode有合法数值则保留原值否则失败为 1、成功为 0。这部分行为在 extensions/tokenjuice/index.test.ts 有直接验证当 bash 只提供truncation、fullOutputPath等元数据时中间件会补上status: completed与exitCode: 0同时不携带aggregated。测试还逐一覆盖了exitCode: 7、success: false、ok: false、timedOut: true、error: ...等失败推导路径extensions/tokenjuice/index.test.ts确认这些场景都会被归一化为status: failed。4.3 压缩结果受宿主上限保护测试 extensions/tokenjuice/index.test.ts 演示了一个 120,000 字符的原始输出在中间件管线中替换为 compacted并且details携带tokenjuice: { compacted: true }标记且保持在中间件 details 限制之内。这说明压缩后的结果仍然会遵守宿主对details体积的限制不会因为压缩逻辑本身引入超限负载。五、验证 Tokenjuice 是否生效按文档给出的步骤操作即可启用插件见上文 2.2 节启动一个可以调用exec的会话运行一条嘈杂命令例如git status检查返回的 tool result 是否比原始 shell 输出更短、更结构化。如果返回结果出现了结构化的压缩标记例如details中带有tokenjuice.compacted这样的元信息且原始命令的退出码与执行语义保持一致即可确认插件处于生效状态。六、关闭插件当不需要压缩、希望所有场景都拿到逐字输出时两种方式任选其一openclaw config set plugins.entries.tokenjuice.enabled false或者openclaw plugins disable tokenjuice关闭后exec/bash的工具结果将恢复原始形式不再经过 tokenjuice 的 reducer 处理这也再次印证了它“opt-in、可逆”的设计定位。七、总结与相关文档Tokenjuice 解决的是 Agent 长会话中一个非常具体的痛点exec/bash的原始输出往往充满噪音、占用大量上下文窗口。它通过 tool-result 中间件在结果回灌前完成压缩同时严守“不改命令、不重跑、不改退出码”的边界并以 safe-inventory 策略保护文件内容读取与不安全命令序列做到在节省 token 与上下文空间的同时不牺牲正确性。对希望控制上下文膨胀、让 Agent 更专注于结构化信息的用户来说这是一个低成本、可随时启停的优化手段。围绕该主题可以继续阅读仓库内相关文档Exec 工具文档Thinking levels 文档Context engine 概念文档插件完整实现与测试见 extensions/tokenjuice包括入口 index.ts、中间件实现 tool-result-middleware.ts、运行时契约 runtime-api.ts 以及行为测试 index.test.ts。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考