QClaw部署依赖与环境配置教程

QClaw本地部署失败？别急着折腾环境——本文直击核心痛点，为你详解“一键自动注入”这一官方推荐的极简方案：下载对应系统安装包、全程默认安装、等待弹窗即刻运行，真正绕过Node.js、Docker、Git等繁琐依赖的手动配置；同时清晰梳理Windows/macOS双平台的手动校验要点与网络端口放行技巧，覆盖从命令行版本验证、Xcode工具链安装到防火墙授权、企业网代理适配等真实场景中的典型卡点，助你5分钟内跨越环境门槛，稳稳启动QClaw核心服务。

如果您尝试在本地电脑上运行 QClaw，但安装失败或启动后报错，则可能是由于系统缺少必要运行环境。以下是满足 QClaw 正常部署与运行的环境准备方法：

一、自动依赖注入（推荐方案）

QClaw 内置全自动环境装配引擎，可绕过所有手动依赖安装环节，直接完成底层组件集成。该机制覆盖 Node.js、Docker Desktop、Git CLI、Python 运行时等全部 OpenClaw 所需依赖，无需用户干预。

1、下载官方 QClaw 安装包（Windows 选择 QClaw-Windows-Setup.exe，macOS 选择 QClaw-Mac.dmg）。

2、双击运行安装程序，全程点击“下一步”与“我同意”，不勾选任何自定义选项。

3、等待安装界面显示“环境检测中…正在安装 Node.js…正在配置 Docker…”提示，保持窗口开启直至出现“部署完成”弹窗。

4、勾选“立即运行 QClaw”，点击“完成”，软件将自动拉起并初始化核心服务。

二、Windows 系统手动预装校验项

当自动注入流程因网络中断、杀毒拦截或权限限制失败时，可提前手动确认关键组件是否存在。此方式不替代自动部署，仅用于故障排查与前置验证。

1、打开命令提示符，依次执行 node -v 与 npm -v，确认输出版本号不低于 v18.17.0。

2、运行 docker --version，确保 Docker Desktop 已安装且服务处于运行状态（托盘图标为绿色）。

3、检查系统环境变量 PATH 中是否包含 Git 安装路径，若缺失则需从 git-scm.com 下载并勾选“Add Git to PATH”完成安装。

4、在 PowerShell 中执行 Get-ExecutionPolicy，若返回 Restricted，需运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 解除脚本限制。

三、macOS 系统基础组件补全

macOS 默认不预装开发工具链，QClaw 自动部署虽可覆盖大部分依赖，但部分系统级权限需用户主动授权，否则 Homebrew 或 Xcode Command Line Tools 初始化会卡住。

1、打开终端，输入 xcode-select --install 并按提示完成 Command Line Tools 安装。

2、执行 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 安装 Homebrew。

3、运行 brew install --cask docker 获取 Docker Desktop，并手动启动应用使其后台常驻。

4、关闭 SIP（系统完整性保护）非必需，但若安装过程中提示“无法写入 /usr/local”，需重启进入恢复模式执行 csrutil disable（操作后务必重启生效）。

四、网络与端口放行配置

QClaw 启动后默认监听本地回环地址的 3000、8080、9000 三个端口，用于 Web 控制台、微信网关通信及模型服务代理。防火墙或安全软件可能阻止其绑定。

1、Windows 用户在“Windows 安全中心 → 防火墙与网络保护 → 允许应用通过防火墙”中，勾选 QClaw 对“专用”和“公用”网络的允许权限。

2、macOS 用户前往“系统设置 → 网络 → 防火墙 → 防火墙选项”，点击“+”添加 QClaw.app 并启用“允许传入连接”。

3、检查企业网络策略：若处于公司内网或教育网，需确认出口代理未拦截 WebSocket 连接（QClaw 微信通信依赖 wss:// 协议）。

4、临时禁用第三方安全软件（如 360、腾讯电脑管家），避免其将 QClaw 的 Docker 子进程误判为挖矿行为而终止。

好了，本文到此结束，带大家了解了《QClaw部署依赖与环境配置教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多科技周边知识！