【免费下载链接】ClawRouterThe agent-native LLM router for autonomous agents. Every frontier model behind one wallet, 1ms local routing, USDC payments on Base Solana via x402.项目地址https://gitcode.com/gh_mirrors/cl/ClawRouter点击查看免费下载导读ClawRouter Desktop 是面向自主智能体Agent的 LLM 路由器 ClawRouter 的本地控制平面control plane以桌面应用形态为 OpenClaw、Codex、Hermes、DeepSeek HarnessDSH与 Pi 提供一键式接入 / 卸载 / 恢复管理。它的核心设计目标有两点一是安全边界——渲染进程React UI永远拿不到文件系统与进程权限一切敏感操作都收敛在沙箱化的 Electron preload 与主进程之间狭窄的 IPC 通道内二是可逆性——每一次配置变更都遵循快照、应用、验证、回滚的事务化契约任何失败都能把 Agent 的配置字节级还原。读完本文你将掌握 Desktop 的架构分层、构建打包流程、钱包共享机制、服务身份验证原理以及事务化回滚的完整实现路径。一、产品定位与总体架构根据 apps/desktop/README.mdClawRouter Desktop 是一个面向 OpenClaw、Codex、Hermes、DeepSeek HarnessDSH与 Pi 的本地控制平面。它不是一个独立的路由器实现而是让 ClawRouterblockrun/clawrouternpm 包以最安全、最可逆的方式接入上述五个 Agent 的安装器 运维面板。其安全模型从架构上就被强制渲染进程零特权Rendererapps/desktop/src/App.tsx不接收任何文件系统或进程访问能力窄 IPC 通道沙箱化的 preload 脚本只向主进程暴露一组白名单 API主进程集中管理所有安装、回滚、钱包、代理proxy生命周期操作都在主进程侧完成。从 apps/desktop/electron/main.ts 可以看到窗口的安全配置webPreferences: { preload: join(__dirname, preload.cjs), contextIsolation: true, nodeIntegration: false, sandbox: true, }contextIsolation: true、nodeIntegration: false、sandbox: true三者同时启用再配合will-navigate拦截只允许加载受信任的渲染文件与setWindowOpenHandler拒绝一切新窗口构成了一个非常收敛的攻击面。主进程 / Preload / 渲染进程的职责划分apps/desktop/electron/main.ts 注册全部 IPC handleragents:statuses、agents:install、agents:uninstall、dashboard:get、wallet:switch-chain、wallet:create、wallet:adopt-legacy、wallet:create-onramp、external:open。每个 handler 第一行都会调用requireTrustedRenderer(event)校验消息来源apps/desktop/electron/preload.ts 通过contextBridge.exposeInMainWorld(clawrouter, ...)只暴露这 9 个方法每个 IPC 入参都会经过 apps/desktop/electron/core/ipc-policy.ts 的严格校验参数校验规则ipc-policy.tsagent必须属于{openclaw, codex, hermes, dsh, pi}白名单options只允许setDefault布尔与model匹配^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$两个键chain只能是base或solanaamount必须是$1 ~ $2,500之间的有限数字且四舍五入到分url必须是https:无账号/密码/端口且主机名限定为github.com与pay.coinbase.com渲染器来源必须为file:协议且解析路径等于打包的index.html不允许 query 或 hash二、开发、测试与发布构建2.1 开发命令README 给出的开发命令为npm install npm test npm run typecheck npm run build npm start结合 apps/desktop/package.json 的 scripts完整的命令表如下命令作用npm run dev启动 Vite 开发服务器仅渲染进程热更新npm test运行 Vitest 测试套件npm run typechecktsc --noEmit全量类型检查npm run buildvite build渲染层esbuild打包主进程/preload 为dist-electron/*.cjsnpm run build:icon通过scripts/render-icon.cjs用 Electron 渲染应用图标npm start启动electron .npm run stage:runtimecorepack pnpm install --dir runtime --prod --frozen-lockfile用冻结的 lockfile重建运行时依赖npm run verify:runtime运行scripts/verify-runtime-pin.mjs校验运行时版本钉扎npm run dist依次执行stage:runtime → verify:runtime → build → build:icon → electron-builder --mac dirnpm run dist:release同上但最终产出electron-builder --mac zip即上传到 GitHub Release 的 macOS ZIP2.2 运行时打包策略版本钉扎与冻结依赖README 特别强调了几条打包原则在 apps/desktop/package.json 与 apps/desktop/electron/core/runtime.ts 中可以得到印证ClawRouter 本体不随包发行npm run dist只预打包钉住的 Codex bridge、DSH 与 Pi 运行时ClawRouter 自身在首次使用时从当前 npm release 安装ensureNpmPackage(…/clawrouter, …, { enforceVersion: true, version: CLAWROUTER_PACKAGE_VERSION })从而保证桌面端永远不会把过时的路由/插件生命周期随包发出版本一致性由测试强制CLAWROUTER_PACKAGE_VERSION 0.12.281在 apps/desktop/electron/core/runtime.ts 定义注释明确与根包保持同步runtime-version.test.ts强制执行对应测试见 apps/desktop/tests/runtime-version.test.tsNode 运行时内嵌Electron 44 内嵌 Node 24最终用户不需要单独安装 NodewithEmbeddedNode()apps/desktop/electron/core/process.ts会在~/.clawrouter-desktop/embedded-node下创建指向process.execPath的node符号链接Windows 下为node.cmdshim并以ELECTRON_RUN_AS_NODE1 前置 PATH 的方式让 npm 包里的.binshebang 找到 NodeHermes 保持独立Hermes 安装在自己独立的 Python 环境中不并入 Node 运行时发行依赖冻结分发命令会用提交进仓库的runtime/pnpm-lock.yaml重新生成runtime/node_modules本地残留不会污染发布产物extraResources把runtime含 lockfile 与node_modules整体带入应用资源目录同时bundledBin()优先从process.resourcesPath/runtime/...解析二进制。ensureNpmPackage()apps/desktop/electron/core/runtime.ts的安装流程是先找钉扎版本 → 再找本地已存在命令按~/.local/bin、~/.npm-global/bin、~/.volta/bin、~/.bun/bin、~/.asdf/shims、~/.hermes/.../venv/bin、Homebrew、nvm 等候选路径依次探测→ 都没有才npm install --ignore-scripts --prefix stateDir/runtime pkgversion安装后还会校验实际安装版本与请求版本一致。三、服务生命周期代理与 Codex bridge 的健康 所有权双重验证Desktop 通过ServiceSupervisorapps/desktop/electron/core/supervisor.ts管理两个子服务本地端点如下README Local endpoints 一节端点服务说明http://127.0.0.1:8402/v1ClawRouterOpenAI 兼容 API本地代理http://127.0.0.1:8403/v1Codex Responses bridgeCodex 接入桥http://127.0.0.1:8402/v1/modelsClawRouter模型目录与元数据两个服务都只绑定回环loopback地址。README 强调了两条安全规则源码中都有对应实现3.1 端口 8402 的令牌证明要求代理启动前Desktop 会先通过ensureServiceToken()apps/desktop/electron/core/service-auth.ts在~/.clawrouter-desktop/service-token创建/读取一个 32 字节随机十六进制令牌0600 权限、wx原子创建。随后verifyClawRouter()同文件 L29-L55执行挑战-响应 HMAC 身份验证生成 32 字节随机 challenge随X-ClawRouter-Challenge请求头发送到http://127.0.0.1:8402/health要求响应体满足status ok且wallet为字符串用令牌对 challenge 计算HMAC-SHA256与响应头x-clawrouter-proof64 位十六进制做timingSafeEqual常量时间比较。只有同时满足以上三点Desktop 才会认为 8402 上的进程是自己可信的 ClawRouter 实例从而复用它而不是再起一个否则会启动新代理并等待其健康。换句话说8402 端口上的服务必须证明自己持有 Desktop 的私有令牌否则不会被信任或复用。3.2 端口所有权的进程树校验对于新启动的服务waitForOwned()apps/desktop/electron/core/supervisor.ts不仅做健康探测还会用childOwnsPort()验证监听该端口的进程属于 Desktop 启动的子进程树listenersOnPort()用lsof -nP -iTCP:port -sTCP:LISTEN -t拿到监听 PIDlistenersOwnedBy()通过ps -o ppid向上回溯最多 12 层父进程确认监听者要么是子进程本身、要么是其后代健康探测需要连续两次通过间隔 150ms才算就绪防止瞬时假健康。README 的表述是supervisor 同时验证监听进程属于子进程树它从不杀死或不信任未知拥有者。 这一点在restartProxy()中体现得最明显当代理不是 Desktop 启动的子进程比如是 OpenClaw gateway 或终端里手动启动的实例时restartProxy()直接返回false把由用户自行重启的选择权交还给用户——Desktop 绝不越权处置不属于自己的进程。stopProxy()里对子进程用 SIGTERM 优雅停止5 秒宽限STOP_GRACE_MS对确认仍持有端口的后代进程才升级 SIGKILL且在升级前会重新读一遍端口持有者避免 PID 复用误杀。3.3 自动启动开关apps/desktop/electron/main.ts 显示应用启动时会自动manager.supervisor.ensureProxy()但设置环境变量CLAWROUTER_DESKTOP_DISABLE_AUTOSTART1可以关闭自动拉起代理。退出时before-quit会调用stopAll()对管理的子进程统一发 SIGTERM。四、共享 BlockRun Core 钱包4.1 钱包文件与来源Desktop 从以下三个文件读取 Base、Solana 与支付链状态README Shared BlockRun Core wallet 一节实现见 apps/desktop/electron/core/manager.ts文件内容~/.blockrun/.sessionBaseEVM私钥形如0x 64 位十六进制~/.blockrun/.solana-sessionSolana 密钥形如[seed(32)…, public(32)…]的 JSON 数组64 字节其中后 32 字节必须能由前 32 字节经 Ed25519 派生验证~/.blockrun/.chain当前支付链base或solana共享的含义是ClawRouter Desktop 与 BlockRun Core 共用这一套钱包状态Desktop 绝不单独持有另一套秘密。余额查询走公开 RPCBase 用https://mainnet.base.org对 USDC 合约0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913做eth_callbalanceOfSolana 用https://api.mainnet-beta.solana.com的getTokenAccountsByOwner按 USDC mintEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v聚合余额均带 30 秒BALANCE_CACHE_TTL_MS缓存。4.2 旧钱包迁移策略绝不覆盖现有 Core 钱包README 明确首次使用时只有当 Core 文件不存在时才把~/.openclaw/blockrun/下的旧 ClawRouter 钱包复制为对应 Core 文件旧文件保留用于回滚Desktop 永不覆盖已有的 Core 钱包。migrateLegacyWalletToCore()apps/desktop/electron/core/manager.ts的具体做法是Core 无.session且旧目录存在wallet.key0x64 位十六进制→ 写入.sessionCore 无.solana-session且旧mnemonic通过scure/bip39校验 → 由助记词经deriveSolanaKeyBytes派生种子并拼上 Ed25519 公钥序列化为 JSON 数组写入Core 无.chain且旧payment-chain是base/solana→ 写入.chain。三个写入全部使用writeFileIfMissing()——即以mode: 0o600, flag: wx原子创建文件已存在则直接失败返回绝不覆盖。adoptLegacyWallet()用户显式触发收养旧钱包则会先把现有 Core 钱包备份为.session.backup-时间戳/.solana-session.backup-时间戳再用atomicWritePrivateFile()临时文件 rename同样 0600 权限原子落盘。4.3 切换支付链switchPaymentChain()manager.ts L154-L223的流程是先确保安装钉扎版本的blockrun/clawrouter→ 执行clawrouter chain base|solana→ 修改~/.blockrun/.chain→重启 Desktop 自己启动的本地代理因为代理只在启动时读取一次链配置→ 通过/health?fulltrue的paymentChain字段确认切换生效。若代理不是 Desktop 启动的则返回restartRequired: true提示用户自行重启网关代理重启失败也会返回restartRequired: true并给出明确错误文案绝不假装成功。五、一键接入的事务化契约5.1 五步契约README 的 One-click contract 一节把每个适配器adapter的接入都约束为同一套事务快照捕获目标配置与权限的精确当前状态健康确保本地代理以及需要时的 Codex bridge健康可用只应用该 Agent 的集成只写入这一个 Agent 的 ClawRouter 配置不动其他 Agent验证校验写出的文件与端点失败回滚任何一步失败都回滚本次尝试。5.2 实现层ConfigurationTransactionapps/desktop/electron/core/transaction.ts 把上述契约落实为ConfigurationTransaction首次快照ensureOriginalSnapshot()在~/.clawrouter-desktop/backups/agent.json保存version: 1清单含每个受管路径的existed、contentBase64、mode、符号链接目标等这是接入前原始配置的唯一权威备份每次尝试快照run()在应用操作前先对受管路径再做一次beforeAttempt快照操作抛错时restoreFiles(beforeAttempt)还原到本次尝试前的状态并抛出RolledBackError回滚成功或RollbackError回滚也失败消息中会说明原因清单校验读取备份时validateManifest()会校验版本、agent、路径集合与文件条目完整性validateSymlinkTargets()还会核对当前符号链接目标与解析路径是否与清单一致——损坏的备份会被拒绝使用此时状态面板会把该 Agent 标记为needs-attention见decorateStatus()而不是带着坏备份继续工作。文件层的支持实现见 apps/desktop/electron/core/files.tssnapshotFiles()记录文件内容base64、权限位mode 0o777与符号链接语义restoreFiles()能按existed标志删除安装时新建的文件、重建符号链接、原子写回原字节与原权限resolveWriteDestination()会解析最多 16 层符号链接链并拒绝循环链防止写入被重定向到意外位置。5.3 卸载与还原先前配置若存在 Desktop 首次托管前的原始备份卸载时restoreOriginal()直接按原字节与原 mode还原README 原话restore the original bytes and mode captured before the first Desktop-managed install并删除备份清单若该 Agent 在 Desktop 之前就已手工配置过 ClawRouter无备份则走adapter.disconnect()只移除 ClawRouter 相关设置、保留其他配置并在状态里说明没有原始备份缓存的运行时包可能残留在磁盘上但它们是惰性的不会改变 Agent 的配置README 明确这一点。install()与uninstall()的整体编排在 apps/desktop/electron/core/manager.ts五个适配器OpenClaw、Codex、Hermes、DSH、Pi统一实现AgentAdapter接口id、status、install、verify、managedPaths、cleanupRuntime、disconnect等见 apps/desktop/electron/adapters/ 目录与公共辅助 apps/desktop/electron/adapters/shared.ts。5.4 激活方式与用户提示不同 Agent 应用配置后生效方式不同activationMessage()manager.ts L656-L679会根据adapter.activation给出准确提示immediate如 Pi、Hermes无需重启Pi 可在运行中的会话里按CtrlL打开/model立即刷新Hermes 可用/model切换新会话直接生效restart-gateway如 OpenClaw需重启 OpenClaw gateway其他需重启对应 Agent。六、DSH 现状说明README 单独用一节说明 DSHDeepSeek Harness的状态要点如下DSH 仍是developer preview且不发布官方 GitHub release 二进制因此在点击安装的瞬间临时安装它的 npm 依赖图对一键体验来说太慢所以发布构建会预打包其钉扎的运行时DSH 适配器会写出官方 harness 使用的当前settings.yamlprovider 形态以及带版本的.credentials.yamlversion: 1、refs:结构。对应的 CLI 行为测试见 apps/desktop/tests/dsh-cli.test.ts验证了适配器对 DSH CLI 输出/配置格式的解析。七、安全与回滚机制的测试验证Desktop 的安全与事务逻辑有专门的测试覆盖值得读者对照阅读apps/desktop/tests/ipc-policy.test.tsIPC 入参校验非法 agent、未知选项、非法链、越界金额、非白名单外部 URL 等一律拒绝apps/desktop/tests/transaction.test.ts配置事务的快照/回滚/还原语义apps/desktop/tests/supervisor.test.ts端口所有权判断与进程树归属apps/desktop/tests/process.test.ts命令执行、输出上限1 MiB 截断与超时apps/desktop/tests/manager.test.ts管理器层面的安装/卸载/钱包/仪表盘编排apps/desktop/tests/runtime-version.test.ts强制CLAWROUTER_PACKAGE_VERSION与根包一致apps/desktop/tests/config.test.ts桌面端配置结构。八、小结把一键接入变成可验证、可回滚的操作ClawRouter Desktop 的价值不在于重复实现路由器而在于把把某个 Agent 接进 ClawRouter这件原本需要手工编辑配置、验证端点、处理失败后果的事压缩为一个有事务语义、有身份验证、有所有权边界、有字节级回滚的确定性操作。无论是对 OpenClaw 这类需要重启网关的 Agent还是 Pi/Hermes 这类即时生效的 Agent桌面端都通过统一的五步契约保证快照先行、只改该 Agent、写后验证、失败还原。配合共享 BlockRun Core 钱包的绝不覆盖 旧钱包保留回滚策略以及 8402/8403 端口上的令牌证明与进程树所有权校验它从两个维度同时回答了如何安全地替用户改配置与如何安全地替用户管钱包这两个问题——这正是 Agent 时代本地控制平面应该具备的最小可信基座。赞分享【免费下载链接】ClawRouterThe agent-native LLM router for autonomous agents. Every frontier model behind one wallet, 1ms local routing, USDC payments on Base Solana via x402.项目地址https://gitcode.com/gh_mirrors/cl/ClawRouter点击查看免费下载相关推荐Umi-OCR完全指南如何免费实现高效离线文字识别Umi OCR完全指南如何免费实现高效离线文字识别 在日常工作中你是否经常遇到需要从图片、PDF或截图中提取文字的困扰无论是处理扫描文档、整理会议记录还OCR桌面应用Hermes Desktop 应用接入 Hindsight 长期记忆Settings 内一键配置实战指南Hermes Desktop 应用接入 Hindsight 长期记忆Settings 内一键配置实战指南 本篇指南讲解如何在 Hermes Desktop 桌人工智能AI AgentAgent 记忆MCP 服务Hindsight × OpenClaw 集成实战为 OpenClaw Agent 接入本地持久化记忆Hindsight × OpenClaw 集成实战为 OpenClaw Agent 接入本地持久化记忆 本篇技术指南聚焦 Hindsight 官方 OpenC人工智能AI AgentAgent 记忆MCP 服务上一篇如何在Android设备上安装和配置NeoTerm从零开始的完整指南下一篇2024年最新版Briefing功能详解Vue3迁移与TypeScript重构带来的提升创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考