危险命令审查闸 BlockRunAI/dsh-clawrouter

给你的 DeepSeek Harness 智能体装上第二大脑

DeepSeek 又快又便宜——循环里继续用它。
这个插件补上它做不到的事：危险命令执行前，先让更强的模型审查一遍。
75 个模型，一份凭证就能用——去 user.blockrun.ai 拿 API key，或者不想注册就用 Solana 或 Base 钱包。

dsh-clawrouter 是 DeepSeek Harness 插件，在智能体执行危险操作之前，先让更强的模型把关。智能体提出 rm -rf ~ 时，审查模型会读一遍，然后给出 allow / deny / ask，由真正的工具执行器强制执行，而不是靠提示词。它还注册了一条 BlockRun 服务商路由，所以审查模型（以及任意 75 个模型）都能用一份凭证访问：从 user.blockrun.ai 拿到的 BlockRun API key，按实际 token 用量计费——或者，如果你不想注册任何东西，也可以用 Solana 或 Base 钱包，通过 x402 用 USDC 按请求付费。MIT 协议。

dsh plugin --profile web add dsh-clawrouter

为什么会有这个插件

Harness 讨论区里，大家反复问的就是这两件事：

「是否有类似 Codex 或者 CC 的审查模式？即额外调用模型审查指令，以解放双手？Full Access 还是太让人担心了。」
— #421 Is there a review mode like Codex or Claude Code — call an extra model to review the command, to free up my hands? Full Access is too worrying.

「使用 Full Access 模式创建并测试插件时误删了我的整个家目录」— #461 Testing a plugin in Full Access mode, it deleted my entire home directory.

Full Access 是全有或全无：要么每条命令都手动批准，要么什么都不批，然后听天由命。这个插件给出了第三种选择。

对比

| | 全部批准 | Full Access | 权限规则 | dsh-clawrouter |
| 解放双手 | 否 | 是 | 是 | 是 |
| 能拦住 rm -rf ~ | 只有你注意到才行 | 否 | 只有你写了规则才行 | 是 |
| 能理解意图 | 靠你 | 谁都做不到 | 否——字面匹配 | 是，模型会读 |
| 在哪里强制执行 | UI 提示 | — | 执行器 | 执行器 |
| 失败时 | — | 放行 | 拦截 | 交给人，绝不放行 |
| 审查日常工作 | 全部 | 不审查 | 不审查 | 不审查 |

它做什么

1. 审查关卡

智能体提出破坏性操作时，强模型（默认 anthropic/claude-opus-5）会读一遍，然后给出结论：

| 结论 | 会发生什么 |
| safe | 进入正常权限链，不受影响 |
| dangerous | 拒绝，并给出智能体能据以行动的理由 |
| uncertain | 升级给你——走正常审批提示 |
它只会收窄权限。审查器放行的调用，仍然要过你已有的每一道沙箱、权限和审批关卡——升级也一样听它们的：如果更严格的策略本来就会拒绝这次调用，你拿到的是拒绝，而不是审批提示。它不替代你的权限系统，只是挡在它前面。

在配置档的 cordis.patch.yml 里启用：

- id: blockrun-review
config:
enabled: true
reviewerModel: anthropic/claude-opus-5

审查什么。 刻意收得很窄——一道对日常工作也触发的关卡会被关掉，然后它谁也保护不了。读取、编辑和构建从不审查。内置规则会标记递归删除、裸磁盘写入、fork 炸弹、curl … | sh、强推和硬重置、chmod 777、sudo，以及任何触碰 ~/.ssh、~/.aws 或 /etc/passwd 的操作——还有那些不写作 rm 的破坏：git clean -fdx、find … -delete、git checkout -- .、terraform destroy，以及 npm publish（registry 不会让你撤回一个发布）。

提到某条命令不等于运行它——grep -rn "rm -rf" docs/ 不会被标记——写下一条命令也不算：包含 rm -rf build 的 Makefile、清理脚本，或引用 git reset --hard 的 README，都是日常工作。文件正文参数（content、new_string、diff 等）按数据处理，因为文件最终做什么，发生在有东西执行它的时候，而那次执行是另一次调用，这道关卡照样会读。添加你自己的规则：

extraRules:
- name: no-prod-deploy
pattern: "deploy\\s+--env[= ]prod"

如果你把 reviewerModel 打错了，每条被标记的命令都会升级或被拒绝——看起来和关卡谨慎工作一模一样。现在失败会带上原因，所以拒绝信息读作「BlockRun does not serve model … Did you mean …?」，而不是干巴巴的超时，并且在任何组装了日志导出器的地方都会记录一条警告。

审查器联系不上时，关卡升级给你（onReviewerFailure: ask，默认值）。它从不悄悄放行——一道失败即放行的安全关卡比没有还糟——也从不因为网络抖动就硬拦。无人值守的自动化可以设为 deny。

一直开着的代价

实测数据，因为这正是决定你要不要继续启用它的问题：

| 对日常工作触发 | 从不——59 条里 0 条，包括那些仅仅提到破坏性命令的命令（grep -rn "rm -rf" docs/、echo "DROP TABLE" >> notes.md） |
| 漏掉危险操作 | 没有——39 条里 0 条，覆盖 git、容器、集群、云存储、数据库和主机状态 |
| 抓住之后才执行的文件 | git 钩子、CI 工作流、shell 启动文件、launch agents、.gitconfig、.env、npm postinstall、沙箱升级——10 条里 10 条，15 次日常文件编辑里 0 误报 |
| 扛住规避 | \rm -rf /、command rm、env rm、eval "rm -rf $DIR"、bash -c "…"、\| xargs rm，以及管道进 shell 的 heredoc |
| 真正触发时的成本 | 在 claude-opus-5 上为 $0.0057，按审查器 512 token 上限计算——不设上限则为 $0.0249 |
| 真正触发时的延迟 | 约 3 秒 |
| 审查器看到的内容 | 约 356 token——被标记的那次调用，不是你的对话 |

这个数字取决于上限。 这个网关按请求报价——输入大小加上所要求的 max_tokens——无论模型怎么回答都按这个量结算，所以一次审查只要申请了它从未用到的空间，每次闸门触发都要为此付费。reviewerMaxTokens（512）就是让一份两字段的 JSON 裁决按一份来计价的东西。在 0.10.0 之前，审查器继承 claude-opus-5 标称的 128,000 token 输出，每次审查要花 $0.28–0.33；如果你还在更早的版本上，请升级，而不是换一个更弱的审查器。

所以在正常工作期间它是隐形的：没有延迟，没有成本，没有提示词。它只在少数值得二次确认的命令上计费约半美分。两个语料库都是测试，所以某条规则一旦开始标记 npm test——或者不再标记 kubectl delete namespace——失败的会是 CI，而不是你的会话。

并非每个危险操作都是 shell 命令。写入 .git/hooks/pre-commit、.github/workflows/ci.yml，或者 npm 的 postinstall，都会在之后运行代码——在下一次提交时，在下一次带着你密钥的 CI 运行时，在别人机器上的下一次 npm install 时。这些比 rm -rf 更安静，也因此更糟：盯着破坏行为的用户什么都不会看到发生。在这些规则存在之前实测，10 个里有 2 个被标记。

召回率是以上一切的天花板： 匹配器从不标记的命令，审查器就永远看不到。这张表更早的一个版本声称什么都没漏掉，而它是拿规则当初为之编写的那六条命令测的。拿上面这 39 条来测，同样的规则只抓到 一条。语料库存在的意义，就是让这个数字再也不能靠信任来接受。

2. /spend

/spend

自进程启动以来这条路由花了多少钱——总计、按模型、token 与费用。

这个数字怎么算，取决于你用的是哪种凭证，因为两者的计费算术确实不同。/spend 会在总计下面那句话里说明它用的是哪一种。

用 API key 时： 按服务商上报的 token 计价，费率取自目录里公布的每百万 token 价格。这与你账户被开票的依据相同——没有按次费用，没有最低消费——所以这个数字与 /dashboard/activity 对得上，而不是近似它。拿真实账户主机实测：openai/gpt-5.5 在 16 输入 / 17 输出 token 下报出 $0.000590，也就是 16/1M × $5 + 17/1M × $30。目录里没有公布费率的模型会被计为 unpriced 并如实标注，绝不会悄悄算成 $0。
钱包侧： 网关给出的固定报价，按每次调用计。同一次请求，两条链的报价并不相同——2026-09-05 实测，Base 上是 2000 µUSDC，Solana 上是 1000——所以 /spend 采用调用实际结算那条链的数字（requestFeeUsd、solanaRequestFeeUsd）。一次会话如果两条链都用过，会报告 mixed，并把两者都说明清楚。

以下内容描述的是钱包路径，其中的数字是报价，不是用量。0.11.0 之前，API-key 部署也会报告这些数字，结果把一次由小调用组成的会话夸大了好几个数量级。

你按请求的量付费，不按拿到的量付费。 网关根据请求报价——输入大小加上你指定的 max_tokens——无论模型怎么回答，都按这个报价结算。对照生产环境实测：

| 请求的 max_tokens | claude-opus-5 | deepseek-chat |
| 16 | $0.0020 | $0.0020 |
| 1,000 | $0.0036 | $0.0020 |
| 8,000 | $0.0211 | $0.0020 |
| 60,000 | $0.1511 | $0.0027 |

由此得出两点，第二点要花真金白银。

存在 $0.002 的下限——$0.001 的最低付款加上 $0.001 的固定交易费。低于这个下限，所有报价都一样，这也是 deepseek-chat 在那张表里几乎不动的原因：它足够便宜，即使输出 8,000 token 也仍在下限之内。本节早先的版本正是从这一观察得出结论，说计费按请求而非按 token。可它只在 deepseek-chat 上测过——这条路由上最便宜的模型——下限把费率完全盖住了。

max_tokens 设得大，即使回复很短也照样计费。 这就是 defaultMaxTokens 被限制在 maxOutputCeiling（8,192），而不是取自模型标称的 max_output 的原因。不加限制的话，claude-opus-5 标称 128,000，一个带着这个默认值的请求报价 $0.3211——而完全不加限制是 $0.0216，限制在 1,000 是 $0.0036。成本差八十九倍，全由一个调用方从未设置的字段决定。当某个工作负载确实需要长回复时，再调高 maxOutputCeiling；那时你就是在有意为它付费。

输入大小决定报价的另一半。 同一请求，提示词规模不断增大，max_tokens 保持很小：

| 模型 | 小 | 约 22K 输入 | 约 112K 输入 |
| openai/gpt-4.1-nano | $0.002 | $0.005 | $0.023 |
| deepseek/deepseek-chat | $0.002 | $0.007 | $0.031 |
| google/gemini-3.5-flash | $0.002 | $0.066 | $0.325 |
| anthropic/claude-opus-5 | $0.002 | $0.217 | $1.081 |

一切都从同一个下限起步，随后拉开三十倍以上的差距。一个持有 100K token 上下文的编码智能体，在 DeepSeek 上每次调用大约付下限的十五倍——在 Opus 上则是五百倍。只要你的平均调用携带大上下文，/spend 就会告诉你，并指向你自己模型的费率，而不是一个笼统的数字。它同样看不到付了钱之后失败的请求。你的钱包余额才是权威。
免费模型就是 $0，/spend 也如实这么写。 目录里计费标为 free 的 7 个模型根本走不到 x402 握手 —— 网关直接回 200，不发 402，所以没有报价被签名，也没有任何结算。它们的行显示 $0 N calls (free tier — no payment was signed)，下面那条大上下文警告只按付费调用计算，因为一次从未被报价的调用不可能被低报。在 0.10.3 之前，每次调用一律按固定请求价收费，于是一个试用免费档的会话报出的成本完全是凭空捏造的。

它还会说明是另一个模型作答的。 网关在免费档背后悄悄替换 —— 请求 nvidia/nemotron-3-ultra-550b，大约每三次就有一次由 30B 模型作答 —— 替换者的名字会出现在它流式输出的分块上。/spend 把它打印在你所请求模型那一行下面：

nvidia/nemotron-3-nano-omni-30b-a3b-reasoning $0 3 calls (free tier — no payment was signed) answered by nvidia/nemotron-3-nano-30b on 1 of 3 — the gateway substituted a different model answered by nvidia/nemotron-3-super-120b on 2 of 3 — the gateway substituted a different model

这次调用仍然记在你请求的 id 上，而不是实际作答的 id 上，因为这个计量器对每次调用都按同一个固定数字计价 —— 落在哪一行都改变不了总数，而你选的 id 才是你认得出的那个。

读取 402 报价是免费的，所以上面每个数字都能复现，不用花一分钱。

默认的 requestFeeUsd 是 0.002，因为网关就是这么报价的：一个约 17 token 的请求返回 {"amount":"0.002000"}。BlockRun 公布的定价页面目前写的是 $0.001。

3. /review

/review <paste a diff, a plan, or the agent's conclusion>

用同一个强模型跑你选定的材料。有位用户反馈过这种情况：智能体读到了正确证据，得出了错误结论，只有直接质疑才让真正的 bug 浮出水面。

4. /gate —— 检查网到底有没有张开

/gate # is the gate armed, and with what?
/gate drill # put a dangerous command through the live reviewer

安全功能悄悄关着，比从没装过还糟，因为你已经不再盯着它了。这道闸门可以在用户能看到的一切都正常的情况下处于关闭状态：enabled 默认是 false，补丁层会替换整行 config 而不是合并键，而 /review 无论如何都会注册 —— 所以一个能用的 /review 只能说明插件加载了，完全说明不了工具调用有没有被检查。
/gate 无论 gate 是否已武装都会注册，并会说明当前状态。/gate drill 会把 rm -rf / --no-preserve-root 送进风险匹配器和真实审查器——绝不送到工具——并分别报告每个阶段，因为它们失败的原因互不相关：规则不再匹配是策略问题，审查器不可达是钱包或模型问题。运行时这两者都会塌缩成「升级」，与 gate 正常工作无法区分。drill 就是用来分辨它们的。代价是一次审查器调用。

5. 视觉——给你的智能体一双它没有的眼睛

DeepSeek 不提供视觉模型，所以这是能力问题，不是省钱问题。附上图片，视觉模型就能读出内容：

- id: blockrun-llm
config:
visionModels: [google/gemini-3.5-flash] # narrows the measured default; widen as you verify

网关的 vision 标签不够可靠，所以本插件不信任它。 每个带标签的聊天模型都会收到一张纯色 PNG，并被问它的颜色，共三种不同颜色——其中一种可以猜中——只有三种全答对的模型才会被提供图像输入。你可以用 npm run probe:vision 自己重新测量，它会把列表打印出来供你粘贴回去。测量于 2026-08-31，40 个模型中有 34 个答对：

| 结果 | 模型 |
| 答对 | 所有带标签的 Anthropic、Google、Moonshot、xAI 和 Z.ai 模型；OpenAI 的非 pro 模型，加上 gpt-5.6-sol-pro、gpt-5.6-terra-pro 以及现在的 gpt-5.6-luna-pro；deepseek/deepseek-v4-flash-vision-exp 和 xiaomi/mimo-v2.5 |
| 拒收图像——三次全部 INVALID_REQUEST | openai/gpt-5.2-pro、gpt-5.4-pro、gpt-5.5-pro |
| 回答没有发送图像，因为网关从未发送 | nvidia/llama-3.2-11b-vision |
| 从未测量——应答的是另一个模型 | nvidia/nemotron-3-nano-omni-30b-a3b-reasoning（由 nemotron-3-nano-30b 提供）、qwen/qwen3.8-flash（由 qwen3.7-flash 提供） |

llama-3.2-11b-vision 这一行不是模型的错：网关在派发前会无条件剥掉它两条 NVIDIA 路径上的所有图像部分，注释里还声称 NVIDIA 模型没有视觉能力。直接对 NVIDIA 探测，该模型和 nemotron-3-nano-omni 都能正确说出颜色。它没进列表，是因为这份列表衡量的是经由本网关能用的模型，但这是网关的 bug，正在修复。

最后一行是你在自行扩充列表之前必须理解的。那两个不是失败，而是根本没被触达。nemotron-3-nano-omni 大约一半的探测轮次能通过，其余轮次由没有视觉能力的模型应答，所以放它进来等于买了一条图像通路，只在网关的级联心情好时才工作——心情不好时，回复就是针对一张从未被看见的图像的自信错误答案。qwen3.8-flash 是被更便宜的付费模型替换掉的付费模型，所以这不是免费层的怪癖。已报告为 BlockRunAI/blockrun#450。
gpt-5.6-luna-pro 走的是另一条路，虽然看起来不像这个原因。它根本不是图片失败：目录给它的定价低于 OpenAI 的收费，网关据此推导出上游成本上限，于是每个请求都匹配不到端点，而且它没有声明回退，就直接失败了。重新定价修好了这个模型，图片其实一直都能用。上面三个 pro 条目的单独修复仍未完成，所以它们依然拒绝。

第一次测量（2026-08-16）糟糕得多：OpenAI 在付款后返回 HTTP 400，xAI 返回 503，Anthropic 把 [Error: 400 {"message":"Could not process image"}] 当作助手文本流式输出，于是 harness 看到的是一个普通的成功回合，智能体把错误字符串当成模型写的内容照常处理。网关后来把这三个都修好了，而本插件仍会检测这种确切形态——整条消息只有一段转发的错误——并把请求判为失败，状态码按它本来就是失败来映射。只是提到错误的回答，或者同时调用了工具的回合，都不动。所以只有当网关给模型打上 vision 标签并且它出现在 visionModels 里时，才会给模型提供图片输入；visionModels 默认就是实测集合。两个信号必须一致——只看标签会过度声明，只看列表则会对网关已经重新打标签的模型继续声称支持视觉。

你验证其他模型时自行放宽即可；那是改配置，不是在这里发版。

6. 推理强度

推理模型会拿到 high 和 max，按模型从目录的 reasoning 标签声明。

max 是 DeepSeek 的用词，harness 沿用了它。OpenAI 的用词是 low | medium | high，对别的值会在收款后返回 HTTP 400——所以 max 会翻译成各服务商最接近的值，而不是被拒绝。想要尽可能多的思考，不该因为一个拼写就失败。

向完全不推理的模型请求，是另一种情况，会在本地、付款前拒绝：openai/gpt-4o 会先收费，然后直接拒绝 reasoning_effort。目录说明了哪些模型符合条件，所以发现这一点不花任何代价。

7. 一份凭据使用 75 个模型

注册一条 blockrun 服务商路由，可达 BlockRun 提供的每个模型。这对 DeepSeek 不提供的那些模型最重要——Claude、GPT、Gemini、Grok——而这正是评审者需要的。

有三种付费方式，你选一种。它们不是通向同一件事的三扇门：不同的主机、不同的计费、钱用完时不同的失败方式。

| | API key （推荐） | Solana wallet | Base wallet |
| 凭据 | 来自 user.blockrun.ai 的 brk_live_… | bs58 Solana 私钥 | EVM 私钥 |
| 主机 | api.blockrun.ai | sol.blockrun.ai/api | blockrun.ai/api |
| 计费 | 按公布的价格表精确扣减 token 用量——没有按次调用费，没有最低消费 | 每个请求固定报价，通过 x402 在链上签名并结算 | 同上，在 Base 上 |
| 充值 | 在门户里用卡或电汇 | 把 SPL USDC 转到你自己的地址 | 把 Base USDC 转到你自己的地址 |
| 消费记录在哪看 | 你在 user.blockrun.ai/dashboard 的账户账本 | 钱包余额本身 | 钱包余额本身 |
| 注册 | Google 登录 | 完全不需要 | 完全不需要 |
| 配置键 | apiKeyEnv | solanaWalletKeyEnv | walletKeyEnv |

按这个顺序检查。 API key 优先，因为它是你特意选定的凭据——从一个你只是碰巧导出过的钱包付款，会把本该记在账户上的调用花掉真金白银。Solana 先于 Base 检查： 同时持有两个钱包的部署只说明了它能用哪些链付款，没说明它偏好哪条，而这条路由选 Solana。两个网关提供同一份目录，逐 id 校验一致。

添加凭据不会打扰已有部署：三个都不设，你的配置不会有任何变化。

在 Solana 上付款需要 @solana/web3.js 和 @solana/spl-token。它们是可选的 peer 依赖，所以只用 API key 或只用 Base 的部署不会带上它们：

npm install @solana/web3.js @solana/spl-token

7 个模型在所有路径上都免费。在两个钱包网关上，它们完全不需要凭据——两个网关都免费提供 billing_mode: "free" 模型，所以这条路由发送请求时不索要 key。在 api.blockrun.ai 上仍然会发送 key，因为无论模型多少钱，该主机对未认证请求都返回 401。这份列表从目录实时读取，而不是写死在这里，因为它变化的速度比这个插件发版快。

快速开始

dsh plugin --profile web add dsh-clawrouter
export BLOCKRUN_API_KEY=brk_live_... # or store it via the credentials service

安装时会为六个 harness 包打印 ✕ missing peer。这是预期行为。 harness 本身在运行时提供它们，每个第一方 bundle 都以同样方式声明自己的 peer——另一种做法，也就是直接依赖它们，会让配置档拿到第二份 cordis，并以更难排查的方式弄坏插件。在干净安装上验证过：配置档能组合，dsh --profile web --dump-config 会列出这两行。什么都不缺。

获取 API key

这是最短路径，也是你应该走的路，除非你特意想避开账户。

1. 打开 user.blockrun.ai，用 Google 登录。账户创建时是预付费的，余额为零——注册本身不花钱。
2. 在 user.blockrun.ai/dashboard/credits 充值——刷卡结账，金额较大可以电汇。
3. 在 user.blockrun.ai/dashboard/keys 签发密钥。明文只显示一次，记得当场复制。
4. export BLOCKRUN_API_KEY=brk_live_...

你能得到什么：按 token 精确计费，没有单次调用费，也没有最低消费，每次调用都写进你账户的账本 —— /dashboard/activity 会显示每次请求的 request id、模型、token 数和费用，所以 /spend 和发票可以互相对账。

密钥上没有余额也能访问免费模型；任何带价格的模型都会失败并返回 PAYMENT_REQUIRED，指向充值页面。

或者：用钱包，完全不开账户

BlockRun 也接受钱包签名，按次用 USDC 走 x402 付款。不用注册，不用 KYC，不用信用卡，不用按实验室开账户。支持两条链，这条路优先选 Solana。

Solana

npm install @solana/web3.js @solana/spl-token # optional peers, needed only for this path
export SOLANA_WALLET_KEY=... # bs58 secret key

SDK 会把 Solana 钱包保存在 ~/.blockrun/.solana-session；如果你没有钱包，npx -y @blockrun/clawrouter 会生成一个并打印它的地址。往这个地址发送 Solana 上的 SPL USDC。

Base

- 已经跑过 BlockRun 工具？ 你已经有 Base 钱包了。SDK 把它保存在 ~/.blockrun/.session，ClawRouter 保存在 ~/.openclaw/blockrun/wallet.key。哪个存在就导出哪个：export BASE_CHAIN_WALLET_KEY=$(cat ~/.blockrun/.session)
- 还没有钱包？ npx -y @blockrun/clawrouter 会生成一个并打印它的地址。拿到地址后就停掉它，往这个地址发送一些 Base 上的 USDC，然后导出密钥。

把对应链的 USDC 发到对应地址。它们是不同曲线上的不同密钥，USDC 发错地址就找不回来了 —— 所以这条路上一旦支付失败，报错总会同时给出链名和地址。

Base 上的 $5 USDC 大约能覆盖 2,500 次 gate 审查，按 $0.002 的下限价计费 —— 也大约能覆盖 5 次在 Opus 上携带 100K token 上下文的调用。两个数字都是同样的 $5；充值要按你打算怎么用这条路来算，而不是按它的下限价来算。

或者：都不用

目录里计费标为 free 的 7 个模型，在两个钱包网关上都不需要任何凭证。两个网关都用 200 应答它们，从不发起 x402 握手，所以 dsh-clawrouter 在发送之前不会索要密钥。选 nvidia/nemotron-3.5-lightning 或 cohere/north-mini-code，什么都不用导出就能用。其他所有模型在你设置凭证之前仍然会失败并返回 MISSING_CREDENTIAL —— 这个豁免是按模型给的，从目录里读取，不是普遍放宽。

关于凭证本身

这个插件自己不会读取任何密钥文件。没人配置过的凭证悄悄盖过他们实际配置的那一个，正是 harness 凭证接缝要防止的情况 —— 所以它只会读取你指定的那个引用。
三个键在配置里都是引用（apiKeyEnv、solanaWalletKeyEnv、walletKeyEnv），按请求解析——轮换任意一个，下一次调用立即生效，配置文件里不会出现任何密钥。

配置

blockrun-llm —— 服务商路由：

| 键 | 默认值 | 含义 |
| provider | blockrun | 要注册的 harness 路由键 |
| apiKeyEnv | BLOCKRUN_API_KEY | 凭据引用，存放 BlockRun 账户密钥（brk_live_…）——最先检查 |
| solanaWalletKeyEnv | SOLANA_WALLET_KEY | 凭据引用，存放 bs58 Solana 私钥——在 Base 之前检查 |
| walletKeyEnv | BASE_CHAIN_WALLET_KEY | 凭据引用，存放 EVM 钱包密钥，上面两个都解析不出来时使用 |
| apiKeyUrl | https://api.blockrun.ai | API 密钥认证所用的账户 API 根地址 |
| solanaApiUrl | https://sol.blockrun.ai/api | Solana 钱包付款所用的 x402 网关根地址 |

| apiUrl | https://blockrun.ai/api | x402 gateway root a Base wallet pays |
| timeoutMs | 300000 | per-request timeout |
| auxiliaryModel | (off) | model for the harness's own maintenance calls — see below |
| requestFeeUsd | 0.002 | flat per-request fee on the Base wallet path, used by /spend — the quoted figure, see below |
| solanaRequestFeeUsd | 0.001 | the same figure for the Solana wallet path, which the gateway quotes differently. An API key is billed per token instead and ignores both. |

Cutting compaction cost

The harness compacts long sessions by summarizing them — and it does that on whatever model the conversation is using. On a flagship model that means paying flagship input rates to summarize, repeatedly, for the whole session.

A ~100K-token compaction runs about $0.90 on Claude Opus 5 and about $0.026 on DeepSeek V4 Flash — read from live 402 quotes at that size, consistent with the table above. Summarizing is a job a cheap model does well, and those calls share no prefix with your conversation — so moving them forfeits no prompt-cache hit:

- id: blockrun-llm
config:
auxiliaryModel: deepseek/deepseek-chat

Off by default, and it only ever affects calls the harness itself marks as maintenance (compaction, session titles). A conversation request is never redirected.

blockrun-review — the gate:

| Key | Default | Meaning |
| enabled | false | whether the automatic gate intercepts tool calls |
| reviewerProvider | blockrun | provider route carrying the reviewer |
| reviewerModel | anthropic/claude-opus-5 | use a different, stronger model than the agent |
| timeoutMs | 30000 | how long one review may take |
| reviewerMaxTokens | 512 | output cap asked for per review, and billed whether or not it is used |
| onReviewerFailure | ask | ask escalates to you; deny blocks (unattended runs) |
| extraRules | [] | additional {name, pattern, tools} risk rules |

Mounting the route does not change your default model. dsh-base keeps deepseek-official; this route is used only where you ask for it.

Honest notes

- This will not make DeepSeek cheaper. Each request is priced from its own 402 quote — $0.002 at small sizes, climbing with input — and BlockRun does not price DeepSeek's cache-hit discount. A cache-warm agent turn costs DeepSeek about $0.000056 directly against roughly $0.007 here at 22K input tokens. Keep your DeepSeek key for the loop; use this for what DeepSeek cannot do.
- The free tier is a smoke test, not a workhorse. 7 models are free right now, and they are free because someone else's terms pay for them: the NVIDIA entries may use prompts for service improvement, so do not point them at a private codebase, and never use one as the reviewer. It also turns over fast — on 2026-08-30 NVIDIA retired four of the five free models in a single sweep, and the replacements arrived the same day. This route reads the list live, so it follows those changes without a release here, but a free model you pinned last week may simply not be there.
- A free model can answer as a different model, and /spend will tell you. The gateway keeps a fallback cascade behind the free tier and substitutes without failing. Measured: every request for nvidia/nemotron-3-nano-omni-30b-a3b-reasoning — the free tier's only vision model — was answered by something else, and one request in three for nvidia/nemotron-3-ultra-550b, the largest free model listed, came back from a 30B. One of the substitutes, nvidia/nemotron-3-super-120b, is not in the public catalog at all. Since 0.10.4 this route reads the model field off every chunk and names the substitute under the row in /spend, against the id you asked for rather than replacing it. It is a report, not a guard: the reply is real and it is delivered. Reported upstream as BlockRunAI/blockrun#450.
- A review costs a model call. It runs only on flagged calls, with a 30s ceiling.
- The reviewer sees the flagged tool call, not your whole repository.

Known limitations

- An image is refused for a model measured not to accept one — visionModels is the set that answered a real image correctly, and the vision tag alone is not enough, since several tagged models charge and then fail. Six are excluded; see section 5. (This bullet used to read "images are refused, vision is planned", beside another saying reasoning effort was refused too. Both shipped in 0.10.0 and both bullets outlived them by three releases, describing a plugin that no longer exists — in the section a reader consults precisely to find out what does not work.)
- An aborted request stops delivery immediately, but the in-flight HTTP request is not itself cancelled until @blockrun/llm accepts an AbortSignal; the socket closes on the SDK's own timeout.
- This plugin keeps no durable record of what it spends. /spend lives in memory for the life of the process. Harness session logs refuse event types a build does not know, and an out-of-repo plugin cannot mark its events ignorable, so it writes no session events. It also does not reach ~/.blockrun/cost_log.jsonl: that ledger is written by @blockrun/llm's LLMClient, and the streaming client this adapter uses tracks its spend in memory only. On an API key the durable record is BlockRun's own — every call lands on the account ledger behind /dashboard/activity, with request id, model, tokens and cost. On a wallet, the wallet balance is the record.
- There is no balance or usage endpoint to read from the plugin. api.blockrun.ai publishes /v1/chat/completions, /v1/messages and the model catalogs; /v1/usage, /v1/balance and friends are 404. So /spend cannot show your remaining credit, and an exhausted account is discovered by a PAYMENT_REQUIRED that points at the top-up page rather than by a warning beforehand.
- Solana needs two optional peer dependencies. @solana/web3.js and @solana/spl-token are optional peers rather than dependencies, because @solana/spl-token pulls in bigint-buffer, whose native toBigIntLE() has an unpatched buffer overflow with no fixed release anywhere. Making them optional keeps that out of the lockfile of every API-key and Base-only deployment. Install them yourself for the Solana path; a Solana request without them fails naming the packages.
- The model a response reports is not always the id you asked for, and not always a substitution. OpenAI-family models echo the vendor-versioned id — a request for openai/gpt-5.5 comes back as gpt-5.5-2026-04-23, and anthropic/claude-sonnet-4-6 as anthropic/claude-sonnet-4.6. /spend's substitution line reads those as a different model answering. It is cosmetic and it predates the API-key path — measured identical on both hosts — but it does mean the line can appear when nothing was actually substituted.
- Smart routing (blockrun/auto) is not wired up, and not for lack of a router. A virtual model has to report one context window, and the harness sizes compaction from it: report the largest candidate and a turn routed to a smaller model overflows with compaction never firing; report the smallest and every session compacts far too early. Until that has an honest answer, pin a model id — auxiliaryModel already moves the expensive maintenance calls, which is where the savings actually were.
- Compaction may fire earlier than it needs to. This route reports the context window the gateway's model catalog declares. Measured against the live gateway, openai/gpt-4.1-nano accepted a 450,037-token prompt and recalled a marker from the very first line — no truncation, but 3.5x the 128,000 the catalog states. The harness sizes compaction from the declared figure, so a session can compact while the model would still have taken the whole thing. Reported upstream; this plugin reports what the catalog says rather than guessing higher, because over-claiming would trade early compaction for silent overflow.
- Context overflow is detected by request size, not by the error text. A real overflow comes back from the gateway as {"message":"API request failed"} — the provider's wording is sanitized away, so the usual text detectors match nothing. After a 400, a request larger than the model's declared window is therefore treated as an overflow so compaction can recover. The text detectors still run first, so this corrects itself if the gateway stops sanitizing.
- Prior-turn reasoning is not sent back. DeepSeek's thinking-mode guide says reasoning_content should be returned on tool-call turns, but this one route serves 75 models from many vendors, and a field one of them requires is a field another may reject. Multi-step tool use on a reasoning model may be slightly degraded as a result; please report it if you hit it.

Development

npm test # offline tests, including real-cordis-Loader compositions
npm run test:e2e # live tests, three independent suites that never fall back to each other:
Base wallet (real USDC, ~$0.02), Solana wallet (SOLANA_WALLET_KEY or
~/.blockrun/.solana-session), and the account host (BLOCKRUN_API_KEY).
Each skips when its own credential is absent.
npm run sync:models # refresh the model and free-tier counts in both READMEs from the live catalog
npm run probe:vision # measure which vision-tagged models really accept an image; prints the list to paste
npm run test:docker # install the PUBLISHED package in a clean container and assert it composes

Developing against a linked checkout (dsh plugin add /path/to/dsh-clawrouter) pulls this package's devDependencies into the profile, giving a second copy of @deepseek-ai/dsh-llm. instanceof LlmError then fails across the two copies and the harness reports every failure as UNKNOWN instead of its real code. Test error codes from a packed tarball (npm pack) rather than a link.

The live suites are the only thing that exercises the x402 handshakes, because the signature is the authentication and no mock can stand in for it — and Solana's is a different signature on a different curve, so nothing the Base suite proves carries over. They are also the only thing that proves an API key reaches the account host and is billed the way the account is invoiced. It is deliberately excluded from npm test so it never runs by accident.

Changelog

See CHANGELOG.md. Several early releases fixed silent bugs, so upgrading is worth it if you are on an earlier version.

License

MIT