Tokenless 故障排查

先判断问题发生在哪一层：组件安装、Adapter 接入、压缩处理、统计落盘或 Stash 取回。不要一开始就删除配置或重新安装。

快速诊断

按顺序运行：

tokenless --version
anolisa status tokenless
anolisa doctor tokenless
anolisa adapter status tokenless
tokenless stats status
tokenless env-check --all --checklist

如果某条命令失败，先处理该层问题，再继续后面的检查。查看安装计划但不修改系统：

anolisa --dry-run install tokenless
anolisa --dry-run --verbose install tokenless

system mode 安装应在所有 anolisa 修改命令中保持相同 scope：

sudo anolisa doctor tokenless

`tokenless: command not found`

普通用户安装通常把命令放在 ~/.local/bin。检查：

command -v tokenless
printf '%s\n' "$PATH"
ls -l ~/.local/bin/tokenless

如果 ~/.local/bin 不在 PATH，按照 shell 的启动文件规则加入后重新打开终端。不要为了解决 PATH 问题重复执行 system 安装。

npm 用户还应检查：

npm prefix -g
npm list -g --depth=0 anolisa-tokenless

如果 npm 日志提示跳过 optional dependencies，重新安装：

npm install -g --include=optional anolisa-tokenless

Linux npm 二进制只支持 glibc；Alpine 等 musl 系统需要在 Linux 上从源码构建。

输入和 JSON 错误

错误	原因	处理
`No input provided`	未传 `--file`，stdin 也是终端	使用 `-f <path>` 或管道
`Input exceeds 64 MiB limit`	单次输入超过上限	拆分输入，不要提高系统内存限制绕过
`JSON parse error`	输入不是合法 JSON	先运行 `jq . < input.json`
`Expected a JSON array for --batch mode`	`--batch` 输入不是数组	移除 `--batch` 或修正输入结构
输出仍是原文	压缩后没有估算收益	属正常行为，查看 stderr 提示

启用后没有产生统计记录

1. 验证独立 CLI

printf '%s\n' \
  '{"status":"ok","debug":{"trace":"verbose"},"metadata":null,"data":{"items":[1,2,3]}}' \
  | tokenless compress-response

tokenless stats list --limit 5

如果这里也没有记录，检查：

tokenless stats status
ls -ld ~/.tokenless
ls -l ~/.tokenless/stats.db

压缩无收益时不会记录。测试输入应包含可删除或可截断内容。

2. 验证 Adapter

anolisa adapter scan
anolisa adapter status tokenless

确认：

目标框架已被检测。
Tokenless Adapter 已启用。
Adapter 与组件使用相同的 user/system scope。
启用后已经重启 Agent CLI 或 IDE。

3. 验证 Agent 任务

执行一个确实会经过 Hook 的工具任务，例如有明显输出的 Shell 命令。纯聊天、短响应或框架不提供对应 Hook 时不会产生记录。

4. 检查环境覆盖

env | grep '^TOKENLESS_'

确认没有意外设置 TOKENLESS_STATS_ENABLED=0，并检查自定义数据库路径是否仍位于真实用户 home 下。

Adapter 启用失败

常见原因：

目标 Agent 框架未安装或未被扫描到。
框架版本不满足 Adapter 要求。
Tokenless 安装在 system scope，但用 user scope 修改 Adapter，反之亦然。
npm 安装没有 anolisa 组件记录，却尝试使用 anolisa adapter enable。
OpenClaw 安全策略拒绝 Plugin 所需的 unsafe-install 覆盖参数。

先运行：

anolisa adapter scan
anolisa --verbose adapter enable tokenless <framework>

npm 安装请使用框架集成 · npm 安装后的手动接入。

由 anolisa 管理的安装第一次不会绕过 OpenClaw 安全扫描。只有错误明确给出此建议时，才应在审查报告后重试：

anolisa adapter enable tokenless openclaw \
  --allow-unsafe-plugin-install

npm/手动安装脚本的行为不同：它总是传入 OpenClaw 的 --dangerously-force-unsafe-install，因为 Plugin 会启动固定的 tokenless 和 rtk 子进程。应先审查 Adapter 和安全策略；策略禁止该覆盖参数时不要启用。

命令没有被重写

不是所有命令都有 RTK 重写规则。先独立测试：

rtk rewrite "ls -la"

如果 rtk 不存在：

command -v rtk
tokenless env-check --tool Shell

如果 RTK 正常但 Agent 中不生效，检查框架支持矩阵、Adapter 状态和是否已经重启会话。

TOKENLESS_COMPRESSION_ENABLED=0 不会关闭命令重写。如果必须保留原始 Shell 输入，应禁用 Adapter；使用 OpenClaw Plugin 时也可以设置 rtk_enabled=false。

Tool Ready 报 `NOT_READY`

查看完整清单：

tokenless env-check --tool <name>
tokenless env-check --all --checklist

NOT_READY 表示缺少必需依赖；先处理报告的具体二进制、配置、权限或网络问题。自动修复前先确认变更：

tokenless env-check --tool <name> --fix

--fix 可能调用包管理器或创建链接，不应在不了解输出时直接加 sudo。

数据库错误

`Failed to open database`

ls -ld ~/.tokenless
ls -l ~/.tokenless/stats.db*
env | grep -E 'TOKENLESS_(DATA_DIR|STATS_DB|STASH_DB)='

确认当前用户对选定的数据目录和数据库可写。tokenless CLI 只接受真实用户 home 下的 TOKENLESS_DATA_DIR、TOKENLESS_STATS_DB 和 TOKENLESS_STASH_DB，覆盖值被拒绝时会回退。随包提供的 RTK 统计写入器会直接使用 TOKENLESS_STATS_DB，因此也要移除或修正 Agent 环境中的异常覆盖值。

不要让多个用户共享同一个 stats.db。AgentSight 和 Tokenless 应以能访问同一用户数据库的方式运行。

SLS JSONL 没有记录

tokenless stats status
test -e /var/log/anolisa/sls/ops/tokenless.jsonl

SLS 开关默认开启，但 Tokenless 不创建目标文件。文件不存在时会静默跳过。自定义路径必须位于 /var/log/ 或 /tmp/。

`retrieve` 返回空或失败

检查：

Hash 是否为完整的 24 个十六进制字符。
压缩时是否使用了 --no-stash。
压缩是否处于 active，而不是 dry-run。
是否已超过默认 1 小时 TTL，或被 10,000 条容量策略淘汰。
压缩和取回是否使用相同的用户与数据库路径。
压缩时 stderr 是否报告 Stash 写入失败。

ls -l ~/.tokenless/stash.db*
env | grep '^TOKENLESS_STASH_DB='

显式指定同一数据库重试：

tokenless retrieve <hash> --stash-db ~/.tokenless/stash.db

过期或从未成功写入的内容无法恢复。

有统计记录但 Prompt 没有变小

先查看支持矩阵中的响应交付路径。Qoder 和 Qwen Code 输出 additionalContext，旧版 Copilot Shell 会追加该字段，Codex 则有意保留原始结果，只追加分析或压缩备选。这些路径可以记录变小的候选内容，但不一定减少最终 Prompt。

Claude Code 需要 2.1.121 或更高版本才能替换响应；旧版本或无法识别版本时会透传原文。OpenClaw 会替换持久化结果，但只有设置 toon_compression_enabled=true 才会启用 TOON。

Qoder Plugin 缓存问题

仅在升级后出现以下错误时执行本节：

python3: can't open file '/rewrite_hook.py'

刷新 Adapter：

anolisa adapter disable tokenless qoder
anolisa adapter enable tokenless qoder

确认缓存中没有未展开的占位符：

grep -R -n 'QODER_TOKENLESS_HOOKS' \
  ~/.qoder/plugins/cache/local/tokenless*/*/hooks.json 2>/dev/null

预期无输出。之后完全退出并重启 Qoder IDE。

anolisa 与 RPM 状态不一致

如果曾直接运行 dnf remove 或 rpm -e：

sudo anolisa repair tokenless

按照 repair 输出的计划操作。只有在 RPM 仍存在且输出明确要求重建记录时，才依次执行：

sudo anolisa forget tokenless
sudo anolisa adopt tokenless

forget 只删除 anolisa 状态，不卸载 RPM。

升级与卸载

anolisa 安装

升级：

anolisa update tokenless
anolisa adapter status tokenless
anolisa doctor tokenless

system mode：

sudo anolisa update tokenless

升级后重启已启用的 Agent。通常不需要重新启用 Adapter；如果状态报告资源不一致，再按诊断结果 disable/enable。

卸载前先列出并禁用所有 Adapter：

anolisa adapter status tokenless
anolisa adapter disable tokenless <framework>
anolisa uninstall tokenless

system mode 使用相同 scope。当前版本的 --purge 仅支持通过 anolisa --dry-run uninstall --purge tokenless 预览计划；不带 --dry-run 会返回 NotImplemented，不会卸载组件，也不会删除配置、缓存或状态。实际卸载请使用 anolisa uninstall tokenless，本地数据库处理见清理数据。

npm 安装

升级：

npm install -g anolisa-tokenless@latest

npm 会刷新 Adapter 资源，但框架中已注册的 Plugin 可能仍是旧副本。升级后重新运行目标框架的 scripts/install.sh 并重启框架。

卸载顺序：

bash ~/.local/share/anolisa/adapters/tokenless/<framework>/scripts/uninstall.sh
npm uninstall -g anolisa-tokenless

确认所有 npm 管理的 Adapter 已卸载后，可以删除 npm 复制到用户数据目录的资源：

rm -rf -- ~/.local/share/anolisa/adapters/tokenless

该命令只应在确认目录属于本次 Tokenless npm 安装后执行。cosh 的手动 Extension 需要单独确认并移除 ~/.copilot-shell/extensions/tokenless。

YUM/RPM 安装

优先通过 anolisa 的 system scope 管理。如果安装记录不由 anolisa 拥有，先禁用 Adapter，再执行：

sudo yum update tokenless
sudo yum remove tokenless

升级或卸载不会自动清理用户 home 下的 Tokenless 运行时数据库。

仍无法解决

收集以下信息时先检查并移除敏感内容：

tokenless --version
anolisa --version
anolisa doctor tokenless
anolisa adapter status tokenless
tokenless stats status
tokenless env-check --all --json

不要附加 stats.db、stash.db 或未经审查的 tokenless stats show 输出。

快速诊断​

tokenless: command not found​

输入和 JSON 错误​

启用后没有产生统计记录​

1. 验证独立 CLI​

2. 验证 Adapter​

3. 验证 Agent 任务​

4. 检查环境覆盖​

Adapter 启用失败​

命令没有被重写​

Tool Ready 报 NOT_READY​

数据库错误​

Failed to open database​

SLS JSONL 没有记录​

retrieve 返回空或失败​

有统计记录但 Prompt 没有变小​

Qoder Plugin 缓存问题​

anolisa 与 RPM 状态不一致​

升级与卸载​

anolisa 安装​

npm 安装​

YUM/RPM 安装​

仍无法解决​