1. 项目概述QClaw 一键切换 Crazyrouter 脚本如果你正在使用 QClaw 这款 AI 助手并且对内置的qclaw/modelroute路由模型感到性能或功能上有所局限那么你很可能已经听说了crazyrouter.com这个第三方路由服务特别是它提供的gpt-5.4模型。手动修改 QClaw 的 JSON 配置文件来接入新服务对于不熟悉技术细节的用户来说既繁琐又容易出错。这正是xujfcn/qclaw-crazyrouter这个项目诞生的原因——它提供了一个专为 Windows 用户设计的 PowerShell 一键安装脚本旨在自动化完成从识别配置、备份、添加提供商到切换默认模型的全部流程。简单来说这个脚本就是一个“配置搬运工”和“开关切换器”它帮你处理了所有底层细节让你能快速、安全地体验到 Crazyrouter 的服务。这个脚本的核心价值在于其“一键化”和“无侵入性”。它并非修改 QClaw 的核心程序而是精准地操作其配置文件。对于普通用户它意味着免去了学习 JSON 语法、寻找配置文件路径、担心改错配置导致软件无法启动的烦恼。对于有一定经验的用户它则提供了一种标准化、可复现的配置方法避免了每次重装或换机时的手工操作。无论是想尝鲜gpt-5.4的强大能力还是单纯希望获得更稳定、功能更丰富的模型路由这个工具都能极大地降低你的使用门槛。2. 核心原理与脚本工作机制拆解要理解这个脚本为何有效且安全我们需要先拆解 QClaw 的配置体系以及脚本每一步背后的逻辑。这不仅能让你用得更放心也能在遇到问题时知道从哪里着手排查。2.1 QClaw 配置结构解析QClaw 基于 OpenClaw 框架其用户配置主要存储在%USERPROFILE%即你的用户目录如C:\Users\你的用户名下的几个关键 JSON 文件中。脚本主要操作以下三个文件主配置文件 (%USERPROFILE%\.qclaw\openclaw.json): 这是 QClaw 运行时实际读取的配置。它定义了可用的模型提供商如qclaw、openai、anthropic等、每个提供商的具体参数API 地址、密钥、以及默认的代理Agent设置如默认使用哪个模型。脚本的核心目标就是修改这个文件。兼容性配置文件 (%USERPROFILE%\.openclaw\openclaw.json): 这是 OpenClaw 框架的遗留配置文件路径。为了确保兼容性脚本在修改主配置后可能会将此文件同步为相同的配置防止某些组件或旧版本从错误的位置读取配置。运行时元数据文件 (%USERPROFILE%\.qclaw\qclaw.json): 这个文件通常包含 QClaw 客户端本身的元数据如窗口位置、主题设置等。脚本可能会读取此文件来辅助定位真正的活动配置路径但通常不会修改它。脚本的智能之处在于它并非硬编码这些路径而是通过逻辑判断来定位“真正生效的”openclaw.json文件这提高了在不同版本或自定义安装的 QClaw 环境下的成功率。2.2 脚本执行流程详解当你运行那一行 PowerShell 命令后脚本会按以下顺序执行一系列操作我们可以将其看作一个精心编排的“外科手术”环境检测与路径定位: 脚本首先检查 PowerShell 版本需 5.1然后开始寻找 QClaw 的配置目录。它会优先检查.qclaw目录下的openclaw.json如果不存在则会尝试其他可能路径包括.openclaw目录。这一步确保了脚本能适应不同的用户环境。配置文件备份: 在修改任何内容之前脚本会为当前的openclaw.json创建一个带时间戳的备份文件例如openclaw.json.backup.20250415_143022。这是最重要的安全措施。如果新配置导致问题你可以随时用这个备份文件恢复原状。解析与修改 JSON: 脚本读取现有的 JSON 配置将其转换为 PowerShell 可操作的对象。然后它执行两个关键操作添加crazyrouter提供商: 在配置的providers对象中新增一个名为crazyrouter的条目。这个条目包含了连接 Crazyrouter 服务所需的所有信息API 端点 (baseUrl)、你的密钥以变量形式引用${CRAZYROUTER_API_KEY}、兼容的 API 类型 (openai-completions)以及最重要的——可用的模型定义。这里定义了gpt-5.4模型及其能力支持文本和图像输入上下文窗口 20万 token最大输出 8192 token。设置默认模型: 在agents.defaults.model.primary字段中将值设置为crazyrouter/gpt-5.4。这告诉 QClaw新建对话时默认使用 Crazyrouter 提供的 GPT-5.4 模型。写回与同步: 将修改后的配置对象重新转换为 JSON 格式并写回原配置文件。随后脚本会检查.openclaw目录下的同名文件如果需要会进行同步操作确保配置一致性。善后处理可选: 根据运行参数脚本可能会提示你重启 QClaw 客户端。这是因为 QClaw 通常在启动时加载配置运行时修改配置文件可能不会立即生效需要重启才能应用新设置。注意脚本采用“增量添加”而非“覆盖替换”的策略。它不会删除你原有的qclaw或其他提供商配置。这意味着你的配置文件中将同时存在多个提供商你可以在 QClaw 的界面上随时切换回原来的模型灵活性很高。2.3 安全性与可靠性设计这个脚本在设计上考虑了多种安全边界无网络后门: 脚本代码公开在 GitHub你可以审查其内容。它仅从raw.githubusercontent.com下载自身然后所有操作都在本地进行不会将你的 API 密钥发送到除 Crazyrouter 服务端在你后续使用时以外的任何地方。幂等性操作: 即使你多次运行脚本它也会先检查配置是否已包含crazyrouter提供商避免重复添加造成配置混乱。结构保持: 修改配置时它尽量保持原 JSON 文件的格式和缩进避免因格式错误导致 QClaw 无法解析。错误处理: 理想的脚本应包含基本的错误处理比如文件不存在、JSON 解析失败、路径无权限等情况下的友好提示引导用户解决问题。3. 详细实操步骤与过程记录了解了原理我们来一步步完成实际操作。我将提供两种主要方法最便捷的一行命令法以及更稳妥的下载后执行法。同时也会涵盖一些高级用法。3.1 基础准备与环境检查在运行任何脚本之前做好准备工作能避免大部分问题。获取 Crazyrouter API Key: 访问crazyrouter.com注册账号并登录。在用户面板或 API 设置部分你应该能找到创建或查看 API 密钥的选项。生成一个新的密钥并妥善保存。这个密钥是连接服务的凭证相当于密码。确认 QClaw 安装: 确保你的 Windows 电脑上已经安装并至少成功运行过一次 QClaw。这保证了必要的配置目录和文件已经生成。推荐关闭 QClaw: 在运行脚本前右键点击系统托盘右下角的 QClaw 图标选择退出。这可以防止配置文件被进程锁定导致脚本无法写入。如果忘记退出脚本可能会报错届时再关闭即可。以管理员身份运行: 通常情况下修改用户目录下的配置文件不需要管理员权限。直接以普通用户身份打开 PowerShell 即可。如果遇到“拒绝访问”错误再尝试以管理员身份运行。3.2 方法一经典一行命令直接执行这是项目推荐的最简单方法适合大多数用户。在 Windows 搜索栏输入PowerShell然后点击打开Windows PowerShell不是 PowerShell ISE也不是 CMD。复制以下整行命令务必完整复制从irm到iex结束irm https://raw.githubusercontent.com/xujfcn/qclaw-crazyrouter/main/install-qclaw-crazyrouter.ps1 | iex在 PowerShell 窗口中右键单击选择“粘贴”或直接按CtrlV。此时命令会显示在窗口中。按下Enter键执行。脚本开始运行。首先你可能会看到安全警告因为 PowerShell 默认禁止运行远程脚本。脚本通常会包含Set-ExecutionPolicy -Scope Process Bypass来临时绕过这个限制。如果系统询问是否执行选择[A] 全是(A)或[Y] 是(Y)。脚本会提示你输入 Crazyrouter API Key。将你之前保存的密钥粘贴进去粘贴时可能不会显示星号这是正常的然后按Enter。脚本将自动执行前述的检测、备份、修改流程。你会在屏幕上看到相应的进度信息如 “Backing up config...”, “Adding crazyrouter provider...”, “Setting default model...” 等。最后脚本会询问你是否要重启 QClaw。输入Y并按Enter确认脚本会尝试启动 QClaw输入N则跳过你需要手动启动。实操心得很多新手在这一步出错是因为复制命令时不小心分成了两行。确保在粘贴后整条命令在 PowerShell 中显示为一行。另一个常见错误是当 PowerShell 提示输入Uri时误把 API Key 输入进去。请仔细阅读屏幕提示脚本会明确要求输入API Key。3.3 方法二更稳妥的下载后执行如果你对“直接下载并执行”irm ... | iex这种模式心存顾虑或者遇到网络问题可以使用这个变体。它先将脚本下载到本地临时目录再执行本地文件。打开 PowerShell。复制并执行以下命令$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后续步骤与方法一完全相同输入 API Key跟随提示操作。这个方法的好处是你可以在$env:TEMP通常是C:\Users\你的用户名\AppData\Local\Temp目录下找到下载的.ps1脚本文件。如果执行失败你可以打开这个文件查看内容或者手动运行它进行调试。3.4 高级用法与参数脚本也支持命令行参数适合自动化或静默安装。非交互式运行提供API Key:.\install-qclaw-crazyrouter.ps1 -ApiKey 你的_Crazyrouter_API_Key_字符串这种方式无需手动输入直接开始配置。注意你需要先通过方法二将脚本下载到当前目录或者导航到脚本所在目录再执行。跳过重启提示:.\install-qclaw-crazyrouter.ps1 -ApiKey 你的密钥 -NoRestart使用-NoRestart参数脚本完成配置后不会询问或尝试重启 QClaw直接退出。3.5 配置验证与测试脚本运行完成后不要急于下结论。按照以下步骤验证是否真正生效检查配置文件打开文件资源管理器在地址栏输入%USERPROFILE%\.qclaw并回车。找到openclaw.json用记事本或其他文本编辑器推荐 VS Code、Notepad打开。搜索关键词在文件中搜索crazyrouter。你应该能在providers部分看到一个完整的crazyrouter配置块其中apiKey字段的值是${CRAZYROUTER_API_KEY}这是一个环境变量引用实际密钥由 QClaw 在运行时从内存或安全存储中获取。同时在文件中搜索primary找到agents.defaults.model.primary确认其值为crazyrouter/gpt-5.4。启动 QClaw如果之前没有重启现在手动启动 QClaw。新建对话测试这是关键一步在 QClaw 中务必新建一个对话通常有一个“”或“New Chat”按钮。不要在旧的对话中测试因为旧对话可能缓存了之前的模型设置。在新对话的输入框发送一条消息观察回复是否正常以及界面上的模型标识是否显示为crazyrouter/gpt-5.4或类似字样。4. 常见问题排查与解决方案实录即使脚本设计得再完善在实际操作中也可能遇到各种环境问题。下面是我在多次使用和帮助他人过程中总结的常见问题及解决方法。4.1 脚本执行报错类问题问题现象可能原因解决方案执行策略限制PowerShell 默认禁止运行脚本。在 PowerShell 中临时设置执行策略Set-ExecutionPolicy -Scope Process Bypass然后重新运行脚本。这只是对当前会话生效最安全。irm命令无法识别PowerShell 版本过低 3.0或者处于受限语言模式。升级 PowerShell 至 5.1 或更高版本。检查$PSVersionTable.PSVersion。如果是受限模式可能需要联系系统管理员。“找不到路径”或“文件不存在”QClaw 未正确安装或从未运行过导致配置目录不存在。确保已安装 QClaw 并至少成功打开运行一次生成配置文件。手动检查%USERPROFILE%\.qclaw目录是否存在。JSON 解析错误现有的openclaw.json配置文件格式错误如缺少逗号、引号不匹配。脚本应具备一定的容错能力但如果原文件损坏严重可能会失败。尝试用备份恢复或手动创建一个干净的配置文件可从 QClaw 设置中导出。访问被拒绝配置文件被 QClaw 进程锁定或用户没有写入权限。关闭所有 QClaw 进程包括托盘图标。如果问题依旧尝试以管理员身份运行 PowerShell。4.2 配置后 QClaw 运行异常问题现象可能原因解决方案QClaw 启动失败或闪退修改后的 JSON 配置文件存在语法错误导致 QClaw 无法解析。使用脚本创建的备份文件openclaw.json.backup.时间戳重命名替换掉损坏的openclaw.json。先恢复运行再检查手动修改或重新运行脚本。新建对话无响应或报错1. API Key 无效或未设置。2. Crazyrouter 服务暂时不可用或网络不通。3. 模型标识符拼写错误。1. 检查配置文件中crazyrouter的apiKey字段。如果脚本运行正常这里应该是变量引用。确保在 QClaw 的设置或环境变量中正确配置了CRAZYROUTER_API_KEY的实际值。2. 访问crazyrouter.com检查服务状态或尝试在浏览器中调用其 API 端点需要技术知识。3. 核对配置文件中的model.primary值是否为crazyrouter/gpt-5.4注意大小写和斜杠。模型列表中看不到crazyrouter/gpt-5.4提供商配置未正确添加或 QClaw 客户端缓存了旧的提供商列表。首先确认配置文件已正确修改见3.5验证步骤。然后完全退出 QClaw并可能需要在任务管理器中结束残留进程再重新启动。有时需要清除 QClaw 的本地缓存位置因版本而异通常在%LOCALAPPDATA%\qclaw或%APPDATA%\qclaw下找Cache文件夹。切换回原模型无效脚本错误地删除了原有的qclaw提供商配置。检查配置文件的providers部分是否还存在qclaw条目。如果被删除从备份文件中恢复该部分配置。正常的脚本不应该删除原有配置。4.3 网络与 API 密钥相关问题API Key 已设置但提示无效Crazyrouter 的 API Key 可能有格式要求如前缀cr-或者你的账户没有足够的额度。请登录 Crazyrouter 后台确认密钥状态和余额。脚本下载失败raw.githubusercontent.com在国内访问可能不稳定。可以尝试使用开发者工具F12的网络面板获取脚本内容或通过 Gitee 等镜像站获取如果项目有镜像。也可以直接打开项目 GitHub 页面手动复制install-qclaw-crazyrouter.ps1文件的内容保存到本地运行。连接 Crazyrouter 超时这属于网络连通性问题。可以尝试在命令行用ping crazyrouter.com测试基本连通性或用curl或Invoke-WebRequest测试 API 端点。可能需要检查系统代理设置如果 QClaw 或系统设置了代理需要确保 Crazyrouter 的流量能正确通过。独家避坑技巧在运行脚本前我习惯先手动备份一次配置文件。虽然脚本会自动备份但自己多存一份放在别处更安心。此外如果遇到复杂问题查看 PowerShell 的错误信息详情是关键。在错误信息上右键选择“复制详细信息”粘贴到文本编辑器中通常能获得更具体的错误代码和堆栈跟踪这对于搜索解决方案非常有帮助。5. 手动配置指南与脚本的替代方案虽然一键脚本很方便但了解手动配置的过程能让你在脚本失效或你想进行更个性化定制时游刃有余。手动配置的核心就是直接编辑openclaw.json文件。5.1 手动配置步骤分解定位并备份配置文件关闭 QClaw。打开%USERPROFILE%\.qclaw\openclaw.json先将其复制一份作为备份例如重命名为openclaw.json.manual_backup。添加 Crazyrouter 提供商用文本编辑器打开openclaw.json找到providers: { ... }这个大对象。在现有提供商如qclaw: { ... }的末尾添加一个逗号然后粘贴以下配置块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 } ] }注意 JSON 语法最后一个提供商后面不能有逗号每个键值对用逗号分隔。设置环境变量apiKey字段中的${CRAZYROUTER_API_KEY}是一个环境变量引用。你需要在系统中创建这个环境变量。方法A推荐仅限QClaw在 QClaw 的设置界面中寻找“环境变量”或“API 密钥管理”相关选项添加一个名为CRAZYROUTER_API_KEY的变量值为你的真实密钥。方法B系统级在 Windows 设置中搜索“环境变量”编辑用户变量新建一个变量名为CRAZYROUTER_API_KEY值为你的密钥。注意这种方法会让密钥在系统层面可见安全性稍低。修改默认模型在配置文件中找到agents: { defaults: { model: { ... } } }这个路径。将primary字段的值修改为crazyrouter/gpt-5.4。保存并验证保存文件。确保 JSON 格式正确可以使用在线 JSON 校验工具。然后启动 QClaw新建对话测试。5.2 脚本 vs 手动如何选择使用脚本当你追求效率、避免手动错误、希望快速验证 Crazyrouter 服务时。这是对新手最友好的方式。手动配置当脚本因环境问题无法运行时当你需要配置多个、不同参数的 Crazyrouter 端点时当你想深入理解 QClaw 配置结构进行更复杂的定制如设置多个模型、调整超时参数等时。手动配置的灵活性更高例如你可以定义多个来自 Crazyrouter 的模型或者将 API Key 直接写在配置文件里不推荐因为不安全。但相应地你需要对 JSON 格式和 QClaw 配置结构有更清晰的了解。6. 进阶思考与扩展可能性成功切换至 Crazyrouter 的 GPT-5.4 模型只是一个开始。基于这个配置框架你还可以探索更多玩法。多模型提供商共存与管理你的配置文件中现在至少有两个提供商qclaw和crazyrouter。你可以在 QClaw 的 UI 中在对话时随时切换使用不同的模型。例如对于一些对实时性要求不高的创意写作可以使用功能更强的gpt-5.4对于一些简单的问答切换回内置的qclaw模型可能更快或更经济。理解这一点你就掌握了灵活运用不同 AI 能力的关键。环境变量与密钥管理的最佳实践脚本使用了${CRAZYROUTER_API_KEY}这种环境变量引用的方式这是一种良好的安全实践避免了将明文密钥硬编码在配置文件中。你可以将这种做法推广到其他需要密钥的提供商配置中。考虑使用像direnv或专门的密钥管理工具来管理这些敏感信息进一步提升安全性。监控与调试如果遇到回复慢或错误可以打开 QClaw 的开发者工具如果支持或查看其日志文件观察发送到crazyrouter.com的请求和返回的响应。这有助于判断问题是出在本地配置、网络还是服务端。参与脚本改进如果你发现脚本的某些逻辑在你的环境下不工作或者有改进的想法比如增加对 Linux/macOS 的支持、添加更多错误提示可以到项目的 GitHub 页面提交 Issue 或 Pull Request。开源项目的生命力正来源于社区的共同贡献。这个一键脚本项目本质上是将一次性的、手动的配置过程封装成了一个可重复使用的、健壮的工具。它降低了技术门槛让更多用户能享受到第三方模型服务的优势。通过理解其背后的原理和掌握排查方法你不仅能用好这个工具也能更从容地应对 QClaw 乃至其他类似 AI 客户端的配置挑战。技术工具的价值正在于将复杂留给自己将简便留给用户。