1. 项目概述：一键切换QClaw路由的自动化脚本
如果你正在使用QClaw，并且对内置的qclaw/modelroute路由方案感到性能或稳定性上有所不足，想要尝试更灵活、功能更强大的第三方路由服务，那么你很可能已经听说过crazyrouter.com。这是一个提供高级模型路由和管理的平台，特别是其gpt-5.4模型，在长上下文处理和复杂任务上表现突出。然而，对于大多数Windows用户来说，手动修改QClaw的JSON配置文件来集成新路由，是一个既繁琐又容易出错的过程。你需要定位正确的配置文件、理解其结构、备份旧数据、精确地添加新的Provider配置，最后还要验证修改是否生效。任何一个环节出错，都可能导致QClaw无法启动或功能异常。
这正是xujfcn/qclaw-crazyrouter这个项目诞生的原因。它是一个专为Windows平台设计的PowerShell一键安装脚本，旨在将上述所有手动步骤自动化。你只需要提供你的crazyrouterAPI密钥，脚本就会自动完成从检测、备份、配置到可选重启的全过程。这个工具非常适合那些希望快速体验新路由能力，但又不想深陷配置文件细节的用户。无论你是AI工具的日常使用者，还是希望为团队部署标准化环境的技术人员，这个脚本都能显著降低集成门槛，让你在几分钟内完成从零到一的配置切换。
2. 脚本核心原理与设计思路拆解
2.1 为什么需要自动化脚本？
QClaw作为一款本地运行的AI助手客户端，其核心配置通常存储在用户目录下的JSON文件中，例如%USERPROFILE%\.qclaw\openclaw.json。手动修改这类配置文件主要面临三大挑战：
- 配置文件定位困难：QClaw可能存在多个配置文件（如主配置、兼容性配置、运行时元数据），用户很难确定当前生效的是哪一个。脚本通过查询运行时元数据文件（
qclaw.json）或检查进程环境，可以精准定位到真正被加载的配置文件路径。 - JSON结构复杂易错：配置文件结构嵌套较深，手动添加一个新的Provider（如
crazyrouter）需要严格遵循其JSON Schema。漏写一个逗号、错配一个括号都可能导致解析失败。脚本通过程序化的方式构建和插入JSON对象，确保了语法和结构的绝对正确性。 - 操作缺乏原子性与回滚能力：直接编辑文件是“破坏性”操作，一旦出错，恢复原状可能很麻烦。一个合格的自动化脚本必须包含“备份-修改-验证”的完整流程。本项目脚本会在修改前创建带时间戳的备份文件（例如
openclaw.json.backup.20250415_143022），这为用户提供了“一键还原”的可能。
因此，这个脚本的本质，是将一个需要专业知识（了解文件系统、JSON语法、QClaw配置结构）和细心操作的手动过程，封装成一个对用户透明、安全可靠的自动化流程。
2.2 脚本的工作流程解析
该脚本的执行逻辑是一个典型的“配置管理”流程，设计上充分考虑了健壮性和用户体验：
- 环境检测与准备：首先，脚本会检查PowerShell版本（需5.1+），确保具备必要的Cmdlet支持。然后，它会尝试通过多种方式定位QClaw的主配置文件。优先策略是检查
%USERPROFILE%\.qclaw\qclaw.json这个运行时文件，其中通常包含了活动配置的路径。如果此方法失败，则回退到检测默认路径%USERPROFILE%\.qclaw\openclaw.json是否存在。 - 安全备份：在触及任何现有配置之前，脚本会复制目标配置文件到一个备份位置。这是整个流程中最关键的安全阀。备份文件名包含精确的时间戳，避免了覆盖之前的备份，也让用户能清晰知道哪个备份对应哪次修改。
- 配置读取与合并：脚本使用
Get-Content和ConvertFrom-JsonCmdlet将配置文件解析为PowerShell对象。这样，后续的所有操作（如添加属性、修改值）都是在内存中的对象上进行，而非危险的字符串拼接或正则表达式替换，极大提升了准确性和可维护性。 - Provider注入：脚本会在配置对象的
providers字段下，添加一个新的crazyrouter对象。这个对象的结构是预先定义好的模板，包含了baseUrl、api类型、模型列表等关键信息。用户的API密钥会被安全地填入apiKey字段。这里的设计是“添加”而非“替换”，它保留了原有的qclawprovider，确保了配置的兼容性——万一新路由有问题，用户可以手动在QClaw界面中切换回原路由。 - 默认模型切换：接着，脚本会导航到
agents.defaults.model.primary这个路径，将其值设置为crazyrouter/gpt-5.4。这意味着所有新创建的对话，默认都会使用这个新的路由和模型。这个修改是即时生效的，但通常需要QClaw重新加载配置才能应用。 - 配置写回与同步：将修改后的PowerShell对象通过
ConvertTo-Json转换回格式化的JSON字符串，并写回原配置文件。同时，作为一种兼容性措施，脚本可能会将相同的配置同步到%USERPROFILE%\.openclaw\openclaw.json这个遗留路径，确保不同版本或启动方式的QClaw都能读取到正确配置。 - 善后与重启：最后，脚本会询问用户是否立即重启QClaw。因为配置文件的更改在QClaw运行时可能被缓存，重启客户端是确保新配置生效的最可靠方式。脚本会尝试优雅地结束QClaw进程再启动它，或者提供手动重启的指引。
注意：脚本的整个设计哲学是“最小侵入”和“最大安全”。它不会删除你原有的任何配置，只做增量添加和关键项修改。所有操作都可逆（通过备份文件），并且提供了非交互式运行参数，便于集成到更复杂的部署流程中。
3. 详细使用指南与实操要点
3.1 前期准备工作
在运行脚本之前，确保你的环境满足以下条件，这能避免绝大多数运行时错误：
- 获取Crazyrouter API密钥：这是脚本运行的必要条件。你需要访问
crazyrouter.com官网，注册账号并生成一个API密钥。通常这个密钥是一串以sk-开头的长字符串。请妥善保管，在脚本运行过程中需要输入。 - 确认QClaw安装：脚本不会为你安装QClaw。请确保QClaw已正确安装在你的Windows系统上，并且至少成功运行过一次，以生成初始的配置文件。
- 使用合适的PowerShell：按
Win + X，选择“Windows PowerShell (管理员)”或“终端(管理员)”。虽然非管理员权限也可能成功，但以管理员身份运行可以避免因权限不足导致文件写入失败的问题。检查PowerShell版本，在窗口输入$PSVersionTable.PSVersion，确保主版本至少为5。 - 退出QClaw客户端：强烈建议在运行脚本前，完全退出QClaw。包括系统托盘（右下角）中的QClaw图标，右键点击选择“退出”。这可以防止配置文件被客户端进程锁定，导致脚本无法写入。
3.2 两种核心运行方式详解
项目提供了两种主要的运行方式，适用于不同的安全偏好场景。
方式一：直接执行（最便捷）
这是README中首推的方式，适合追求极致便捷的用户。你只需要打开PowerShell，复制粘贴一行命令：
irm 'https://raw.githubusercontent.com/xujfcn/qclaw-crazyrouter/main/install-qclaw-crazyrouter.ps1' | iex命令拆解与原理：
irm： 是Invoke-RestMethodCmdlet的别名。它的作用是向指定的URL（这里是GitHub Raw链接）发起HTTP GET请求，并获取返回的内容——也就是脚本的源代码。|： 管道符号，将irm获取到的内容（脚本源码）传递给下一个命令。iex： 是Invoke-ExpressionCmdlet的别名。它会将管道传过来的字符串（即脚本源码）当作PowerShell命令来执行。
潜在风险与应对：这种方式本质上是“从网络下载并立即执行”。虽然项目是开源的，但理论上存在中间人攻击或源被篡改的风险（尽管GitHub Raw内容具有完整性）。对于安全性要求极高的生产环境，建议先审查脚本内容。
方式二：先下载后执行（更稳妥）
如果你对直接执行有顾虑，可以使用这个变体命令：
$p = Join-Path $env:TEMP 'install-qclaw-crazyrouter.ps1'; irm 'https://raw.githubusercontent.com/xujfcn/qclaw-crazyrouter/main/install-qclaw-crazyrouter.ps1' -OutFile $p; & $p命令拆解与原理：
$p = Join-Path $env:TEMP ...： 在系统的临时目录（$env:TEMP）下构造一个完整的脚本文件路径。irm ... -OutFile $p： 同样是下载脚本，但这次不是输出到屏幕，而是通过-OutFile参数保存到临时文件（$p）中。& $p：&是调用操作符，它执行指定路径（$p）下的脚本文件。
优势：
- 便于审查：你可以在执行前，用记事本或VS Code打开临时目录下的这个
.ps1文件，查看其具体内容。 - 便于调试：如果执行出错，错误信息会指向一个具体的本地文件路径，更方便定位问题。
- 避免网络问题：脚本只需下载一次，如果执行过程中需要重试，无需重复下载。
3.3 交互式与非交互式运行
交互式运行：直接运行上述任一命令后，脚本会进入交互模式。你会看到类似以下的提示：
正在检测 QClaw 配置... 已在 C:\Users\YourName\.qclaw\openclaw.json 找到配置。 请输入您的 crazyrouter API Key:此时，请粘贴或输入你的API密钥（输入时不会显示字符，这是正常的）。随后脚本会询问是否重启QClaw，按Y或N选择即可。
非交互式运行（适用于批量部署或CI/CD）：如果你已经将脚本下载到本地，或者希望在自动化流程中运行，可以使用带参数的命令：
.\install-qclaw-crazyrouter.ps1 -ApiKey "sk-你的真实API密钥" -NoRestart-ApiKey： 直接提供密钥，跳过手动输入。-NoRestart： 执行完所有配置修改后，不询问也不尝试重启QClaw。这在后台静默部署时非常有用。
实操心得：在个人电脑上，我推荐使用“先下载后执行”的交互式方式。首先，这让我有机会快速瞥一眼脚本内容，确认其没有危险操作（如删除文件、访问奇怪网址）。其次，临时文件在系统重启后会被清理，不留痕迹。对于需要配置多台电脑的情况，则可以将脚本和参数写入一个批处理文件进行非交互式部署。
4. 脚本修改内容深度解析
理解脚本具体修改了哪些内容，有助于你在出现问题时进行手动排查，或者根据自身需求进行自定义调整。
4.1 核心配置变更：Provider的添加
脚本会在你的openclaw.json文件的providers对象中，添加一个名为crazyrouter的新节点。其完整结构如下：
"crazyrouter": { "baseUrl": "https://crazyrouter.com/v1", "apiKey": "${CRAZYROUTER_API_KEY}", "api": "openai-completions", "models": [ { "id": "gpt-5.4", "name": "GPT-5.4", "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 8192 } ] }关键字段解读：
baseUrl： 指向crazyrouter服务的API端点。这表明QClaw后续的模型请求将被发送到这个地址。apiKey：注意这里的值。脚本并不是直接写入你的明文API密钥，而是写入了一个变量占位符${CRAZYROUTER_API_KEY}。在实际运行时，QClaw客户端会从它的环境变量或内部机制中解析这个变量。脚本在修改文件时，会用一个复杂的正则表达式或字符串替换逻辑，将这个占位符替换成你实际输入的密钥。这是一种比硬编码明文密钥更安全的设计模式。api： 设置为"openai-completions"，这告诉QClaw，crazyrouter的API接口与OpenAI的ChatCompletions API兼容。这是目前大多数第三方路由服务采用的兼容模式。models： 定义了一个模型列表。这里只定义了gpt-5.4一个模型。id： 模型在请求中使用的标识符。name： 在QClaw UI中显示的名称。input： 声明该模型支持文本和图像输入。这为多模态功能提供了基础。contextWindow和maxTokens： 分别定义了模型的上下文长度（20万token）和单次回复的最大生成长度（8192 token）。这些参数直接影响你能处理多长的文档和获得多长的回复。
4.2 默认行为的切换：模型优先级设置
添加Provider只是提供了“能力”，要让QClaw默认使用它，还需要修改代理（Agent）的默认设置。脚本会定位到以下路径并修改其值：
"agents": { "defaults": { "model": { "primary": "crazyrouter/gpt-5.4" // 被修改为此值 } } }修改后，所有新创建的“代理”（在QClaw中通常体现为一个新对话窗口或新会话），其首选模型都会是crazyrouter/gpt-5.4。这个值的格式是{provider_id}/{model_id}，清晰地指明了模型来源。
4.3 文件备份策略
脚本的备份操作并非简单的复制。它采用了一种“无损备份”策略：
- 它首先检查目标配置文件（如
openclaw.json）是否存在。 - 如果存在，它会生成一个包含当前日期时间的备份文件名，例如：
openclaw.json.backup.20250415_143022。 - 使用
Copy-Item -Force进行复制。-Force参数可以确保即使目标备份文件已存在（虽然因时间戳不同几乎不可能），也会被覆盖。 - 备份文件与原文件存放在同一目录下，便于查找和管理。
这个策略保证了每次运行脚本，你都有一个独一无二的还原点。
5. 配置验证与问题排查实录
脚本运行完成后，并不代表万事大吉。你需要进行验证，确保配置已正确应用并生效。
5.1 验证配置是否写入成功
- 手动检查配置文件：按下
Win + R，输入%USERPROFILE%\.qclaw并回车，打开QClaw配置目录。用记事本或任何代码编辑器打开openclaw.json。 - 搜索关键内容：
- 按
Ctrl + F，搜索"crazyrouter"，应该能找到完整的Provider定义块。 - 搜索
"primary"，应该能看到其值已是"crazyrouter/gpt-5.4"。 - 特别注意：检查
apiKey字段。它不应该是${CRAZYROUTER_API_KEY}这个占位符，而应该是一串以sk-开头的、看起来是乱码的真实密钥字符串。如果这里还是占位符，说明脚本的密钥替换步骤失败了。
- 按
5.2 验证QClaw是否正常使用新路由
- 重启QClaw：无论脚本是否帮你重启了，自己手动完全关闭再打开一次QClaw是最保险的。
- 创建新对话：在QClaw中，务必新建一个对话（通常是一个“+”号或“New Chat”按钮）。旧对话的会话状态可能会缓存之前的模型设置。
- 发起测试请求：在新对话中，问一个简单的问题，例如“请用中文介绍你自己”。观察：
- 响应速度和质量：crazyrouter的路由可能会带来不同的响应特性。
- 界面提示：有些QClaw版本会在输入框附近或模型选择器中显示当前使用的模型，检查是否为“GPT-5.4”或“crazyrouter/gpt-5.4”。
- 检查网络请求（高级）：如果你熟悉开发者工具，可以打开QClaw的开发者工具（通常基于Electron，可按
F12），在“网络”(Network)标签页中查看请求。成功的请求应该发送到https://crazyrouter.com/v1/chat/completions这个地址。
5.3 常见问题与解决方案速查表
以下是我在测试和使用过程中遇到的一些典型问题及解决方法：
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
运行脚本时提示“无法识别命令irm”。 | PowerShell版本过低或执行策略限制。 | 1. 输入$PSVersionTable.PSVersion检查版本，低于5.1需升级。2. 以管理员身份运行PowerShell，执行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，选择Y。 |
| 脚本执行后，QClaw无法启动或启动报错。 | 配置文件JSON语法错误，通常是脚本修改时格式出错。 | 1. 用JSON验证工具（如在线JSON校验网站）检查openclaw.json文件。2. 最快速的恢复方法是：用脚本生成的备份文件（ openclaw.json.backup.时间戳）覆盖当前的openclaw.json。 |
验证时发现apiKey字段仍是${...}占位符。 | 脚本的密钥替换逻辑未生效，可能因文件编码或特殊字符导致。 | 1. 手动编辑openclaw.json，找到apiKey字段，将其值替换为你的真实API密钥（带引号）。2. 保存文件，重启QClaw。 |
| 新对话中模型显示正确，但发送消息后无响应或报错。 | Crazyrouter API密钥无效、过期，或网络无法访问其服务。 | 1. 前往crazyrouter官网，确认API密钥状态是否正常、是否有余额或调用次数。 2. 尝试在PowerShell中用 curl或irm测试连通性：irm -Uri 'https://crazyrouter.com/v1/models' -Headers @{'Authorization'='Bearer sk_your_key'}，看是否返回模型列表。 |
| 脚本提示找不到QClaw配置。 | QClaw未正确安装，或配置文件不在默认路径。 | 1. 确认QClaw已安装并运行过。 2. 手动在 %USERPROFILE%下搜索openclaw.json或qclaw.json，找到其真实路径。3. 使用本地脚本模式，并考虑手动修改脚本中的路径检测逻辑。 |
| 使用非交互式命令时，参数似乎没生效。 | 参数格式错误，或脚本未以正确路径执行。 | 1. 确保参数-ApiKey的值用双引号括起来，且密钥本身没有多余空格。2. 如果脚本在本地，执行时使用完整路径，如 C:\path\to\install-qclaw-crazyrouter.ps1 -ApiKey "sk-xxx"。 |
5.4 手动回滚方案
如果新路由不稳定或你想恢复原状，手动回滚非常简单：
- 完全退出QClaw。
- 打开资源管理器，进入
%USERPROFILE%\.qclaw目录。 - 你会看到类似
openclaw.json.backup.20250415_143022的文件。选择最新时间戳的那个。 - 将其复制，并重命名为
openclaw.json（覆盖现有的）。 - 重新启动QClaw。此时配置已完全恢复到脚本运行前的状态。
6. 进阶应用与自定义配置建议
这个一键脚本解决了从无到有的问题，但真实的使用场景往往需要更精细的调整。
6.1 多模型配置与管理
Crazyrouter可能提供不止gpt-5.4一个模型。你可以手动编辑openclaw.json，在crazyrouter的models数组里添加更多模型定义。例如，如果crazyrouter还提供了claude-3.5模型，你可以这样添加：
"models": [ { "id": "gpt-5.4", "name": "GPT-5.4", "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 8192 }, { "id": "claude-3.5", "name": "Claude 3.5 (via Crazyrouter)", "input": ["text"], "contextWindow": 150000, "maxTokens": 4096 } ]添加后，在QClaw的模型选择下拉菜单中，你应该就能看到这个新模型选项了。
6.2 脚本的扩展与自定义
如果你有一定的PowerShell基础，这个脚本本身就是一个很好的学习模板和修改起点。
- 修改默认模型：如果你不想用
gpt-5.4作为默认模型，可以修改脚本中$defaultModel变量的值。在脚本里搜索primary赋值的地方进行更改。 - 添加其他Provider：脚本的核心函数
Add-CrazyRouterProvider展示了如何安全地操作JSON配置。你可以模仿这个函数，编写新的函数来添加其他第三方路由服务（如openrouter、together.ai等）。 - 集成到系统部署：对于企业IT管理员，可以将此脚本与软件分发系统（如SCCM、Intune）结合。将脚本和加密的API密钥（通过证书或受保护的变量）打包，实现QClaw客户端的标准化配置推送。
6.3 安全最佳实践
- API密钥管理：脚本运行后，你的API密钥会以明文形式存储在
openclaw.json中。虽然该文件通常在用户目录下，但为安全起见，应避免将此配置文件上传到Git等公开版本控制系统。可以考虑使用系统环境变量来存储密钥，并修改脚本和QClaw配置来读取环境变量，但这需要更深入的定制。 - 脚本来源可信：始终从项目的官方GitHub仓库获取脚本。直接复制他人发来的命令段存在风险。
- 定期审查配置：定期检查
openclaw.json文件，确认其中没有意外的修改或添加未知的Provider。
这个一键脚本极大地简化了QClaw与Crazyrouter的集成过程，将一项可能让新手望而却步的配置任务，变成了几分钟就能完成的简单操作。它的价值不仅在于节省时间，更在于降低了错误率，提供了安全回滚的保障。无论是个人尝鲜还是团队部署，它都是一个非常实用的工具。
