【JiuwenClaw】完整安装踩坑指南（Windows 版）
本文基于真实安装过程整理，包含可直接复制的命令、关键版本限制、必踩的坑和对应解法，帮你一次性搞定 JiuwenClaw 环境配置。
一、前言：先搞懂你会遇到的核心限制
JiuwenClaw 是 OpenJiuwen 推出的龙虾机器人框架，它有一个硬性要求：
Python 版本必须满足
>=3.11 且 <3.14
（也就是仅支持 3.11、3.12、3.13，不支持 3.14 及以上版本）
这是 90% 安装失败的根源，后文会详细说明如何规避。
二、前置准备：确认你的 Python 环境
1. 查看电脑已安装的所有 Python 版本
打开 CMD，执行以下命令：
py -0你会看到类似输出：
-V:3.14 * Python 3.14 (64-bit) -V:3.12 Python 3.12 (64-bit)- 带
*的是系统默认 Python 版本 - 你需要确认电脑上有3.11/3.12/3.13 版本，推荐用 3.12（兼容性最稳）
2. （可选）安装符合要求的 Python 3.12
如果电脑上没有 3.12，直接去官网下载安装：
👉 Python 3.12 官方下载页
安装时必须勾选Add Python to PATH，其他默认即可。
三、Step 1：创建专用虚拟环境
1. 进入你的工作目录
cd D:\AIApplication\JiuwenClaw（路径替换成你自己的项目文件夹）
2. 用 Python 3.12 创建虚拟环境
⚠️ 不要直接用python -m venv，必须指定 3.12 版本！
# 用 py -3.12 强制调用 Python 3.12 创建环境 py -3.12 -m venv jiuwenclaw为什么不能直接
python -m venv？
因为系统默认 Python 是 3.14 的话，创建的虚拟环境也会是 3.14，直接装 JiuwenClaw 会失败。
四、Step 2：激活虚拟环境
jiuwenclaw\Scripts\activate激活成功后，命令行开头会出现(jiuwenclaw)，代表当前环境是独立的虚拟环境。
五、Step 3：安装 JiuwenClaw（官方推荐写法）
1. 先升级虚拟环境内的 pip
python -m pip install --upgrade pip（避免 pip 版本过低导致的安装卡死问题）
2. 安装 JiuwenClaw
⚠️ 必须用python -m pip install，不要直接用pip install！
python -m pip install jiuwenclaw- 全程等待安装完成，直到回到
(jiuwenclaw) D:\...>提示符 - 看到
Successfully installed jiuwenclaw-xxx才算成功，中途报错要重新安装
六、Step 4：初始化 JiuwenClaw 工作空间
安装完成后，执行初始化命令：
jiuwenclaw-init执行过程中会提示：
[jiuwenclaw-init] Do you want to continue? (yes/no):直接输入yes回车即可，它会在C:\Users\你的用户名\.jiuwenclaw目录下生成配置文件。
七、Step 5：微信 iLink Bot 通道配置（Web 控制台版）
初始化完成后，打开 JiuwenClaw 的 Web 控制台，进入「微信频道参数配置」界面，逐项说明如下：
| 参数名 | 配置说明 | 建议值/操作 |
|---|---|---|
enabled | 是否启用该微信通道 | ✅ 打开开关，通道才会生效 |
ilink_bot_id | 微信 iLink Bot 唯一标识 | 绑定微信后自动生成，无需手动填写 |
allow_from | 允许发送消息的用户/群 | 空值=允许所有人；调试阶段建议留空 |
auto_login | 是否自动重连微信 | ✅ 保持开启，掉线自动重连 |
enable_streaming | 是否启用流式回复 | 调试阶段先关闭，稳定后再开启 |
qrcode_poll_interval_sec | 扫码轮询间隔 | 默认 2，无需修改 |
long_poll_timeout_sec | 长连接超时时间 | 默认 45，无需修改 |
backoff_base_sec/backoff_max_sec | 重连退避时间 | 默认 1/30，无需修改 |
关键绑定步骤：
- 微信更新到最新版，进入「我 → 设置 → 插件 → 开启「微信 iLink Bot」」
- 控制台点击「解绑微信账号」，弹出二维码
- 用微信扫码授权绑定，绑定成功后
ilink_bot_id会自动填充 - 打开
enabled开关，点击「保存」 - 重启 JiuwenClaw 服务，微信通道即可生效
八、必踩坑与终极解法
坑 1：安装 JiuwenClaw 时提示「No matching distribution found」
- 原因：你的 Python 版本 ≥3.14，超出了
>=3.11,<3.14的要求 - 解法：删除当前虚拟环境，用 Python 3.12 重新创建：
deactivate rd /s /q jiuwenclaw py -3.12 -m venv jiuwenclaw jiuwenclaw\Scripts\activate python -m pip install jiuwenclaw
坑 2：安装过程中 pip 卡死、报错
- 原因：直接用
pip install命令，安装时 pip 自动升级导致进程卡死 - 解法：全程用
python -m pip install代替pip install，强制使用虚拟环境内的 pip：# 正确写法 python -m pip install jiuwenclaw # 错误写法，容易卡死 pip install jiuwenclaw
坑 3：jiuwenclaw-init命令找不到
- 原因：安装未完成，或虚拟环境未刷新
- 解法：先确认安装完成，再退出并重新激活虚拟环境：
deactivate jiuwenclaw\Scripts\activate jiuwenclaw-init