@licity/qclaw-local-connector 1.1.0

package/.env.example

@@ -0,0 +1,14 @@
+LICITY_API_BASE_URL=https://li.city
+OPENCLAW_CONNECTOR_SECRET=replace-with-your-connector-secret
+CONNECTOR_PROVIDER=qclaw-local
+DEVICE_NAME=
+QCLAW_PATH=D:\QClaw\QClaw.exe
+QCLAW_STATE_DIR=C:\Users\Administrator\.qclaw
+QCLAW_CONFIG_PATH=C:\Users\Administrator\.qclaw\qclaw.json
+OPENCLAW_CONFIG_PATH=C:\Users\Administrator\.qclaw\openclaw.json
+OPENCLAW_CLI_PATH=D:\QClaw\resources\openclaw\node_modules\openclaw\openclaw.mjs
+OPENCLAW_AGENT_ID=main
+OPENCLAW_COMMAND_TIMEOUT_MS=60000
+CAPABILITY_SCOPES=private_chat,neighbor,anchor,time_travel
+HEARTBEAT_INTERVAL_MS=25000
+POLL_INTERVAL_MS=3000

package/README.md

@@ -0,0 +1,419 @@
+# 里世界 QClaw 本地连接器
+
+这是把本机 QClaw 或其他第三方本地 Runtime，桥接到里世界 APP 龙虾系统的本地连接器。
+
+它解决的不是“让 QClaw 自己联网找里世界”，而是另一件事：
+
+- 在你电脑上生成一个给里世界 APP 扫描的连接二维码。
+- 扫码成功后，把某只龙虾和你这台电脑上的 Runtime 绑定起来。
+- 后续由里世界把任务派发给本地连接器，再由本地连接器转给 QClaw/OpenClaw 执行。
+
+如果你是第一次接触这个链路，先记住一句话：
+
+只启动本目录里的连接器还不够。QClaw 主程序、本地 19000 网关、连接器扫码绑定，这三层必须同时成立。
+
+## 安装方式
+
+### 方式一：npm 全局安装（推荐）
+
+```bash
+npm install -g @licity/qclaw-local-connector
+```
+
+安装后，在任意目录创建 `.env` 配置文件（见第 4 步），然后执行：
+
+```bash
+licity-connector
+```
+
+### 方式二：本地克隆 / 下载后运行
+
+进入连接器目录，执行：
+
+```bash
+npm install && npm run quickstart
+```
+
+## 一图看懂
+
+1. 先启动 QClaw 主程序。
+2. 确认 127.0.0.1:19000 已监听。
+3. 创建 `.env` 配置文件并填写必要字段（见第 4 步）。
+4. 运行连接器（`licity-connector` 或 `npm run quickstart`）。
+5. 终端出现二维码。
+6. 打开里世界 APP 的"我的龙虾"，点"扫码连接本地龙虾"。
+7. 选择一只龙虾并确认连接。
+8. 到龙虾私聊页测试文本，再测试截图或文件能力。
+
+## 这套方案现在已经支持什么
+
+当前已经打通：
+
+- 文本私聊回复。
+- 截图类任务回传图片。
+- 第三方 Runtime 按结构化附件格式回传图片或文件。
+- 心跳保活、扫码绑定、换账号接管 Runtime。
+
+当前仍有限制：
+
+- 普通问答是否能真正执行，仍取决于你本机 QClaw/OpenClaw 环境是否可用。
+- 连接器默认通过 JSON 回传附件，建议单个附件控制在 8MB 以内。
+- 如果第三方程序只会回纯文本，不会输出结构化附件，那它就只能回文本，不能自动把本地文件带回里世界。
+
+## 适合谁用
+
+适合以下场景：
+
+- 你已经在电脑上用 QClaw。
+- 你希望把本机 AI 能力映射成里世界里的龙虾。
+- 你想让龙虾能回复文本，或者进一步回传截图、图片、文件。
+
+不适合以下场景：
+
+- 你手里已经是官方 OpenClaw Runtime，并且它本身就能直接生成里世界配对二维码。
+	这种情况优先走官方 OpenClaw 原生扫码，不需要这个桥接器。
+
+## 先说结论
+
+要让龙虾真正工作，至少要同时满足这 3 个条件：
+
+1. QClaw 主程序已经启动，并保持登录和可用。
+2. QClaw 启动后，本机本地网关已经监听，当前实际检查口径是 127.0.0.1:19000。
+3. 本连接器已经启动，并成功和里世界中的某只龙虾完成扫码绑定。
+
+如果第 1 或第 2 条不满足，APP 里给龙虾发消息后，任务虽然会进入队列，但 OpenClaw agent 无法真实执行。
+
+## 目录里有哪些文件
+
+- `index.js`：连接器主程序。
+- `.env.example`：环境变量模板。
+- `setup.js`：本地安装助手和自检脚本。
+- `data/runtime.json`：保存本机 Runtime ID。
+- `data/screenshots/`：截图任务产生的临时图片。
+
+## 新手最短路径
+
+### 第 1 步：启动 QClaw 主程序
+
+QClaw 的位置取决于你的安装路径，常见的在：
+- Windows：`C:\QClaw\QClaw.exe` 或安装时指定的目录
+- 也可以通过桌面快捷方式直接启动
+
+启动后不要立刻关闭，保持 QClaw 正常运行。
+
+### 第 2 步：确认本地 19000 端口已监听
+
+在 PowerShell 执行：
+
+```powershell
+Get-NetTCPConnection -LocalPort 19000 -State Listen
+```
+
+如果能看到监听结果，说明 QClaw 本地网关已经起来。
+
+如果没有结果，优先检查：
+
+- QClaw 是否真的已经启动。
+- QClaw 是否卡在登录页、权限弹窗、升级弹窗。
+- 刚启动时是否还没完全拉起网关，等 5 到 15 秒再查一次。
+
+### 第 3 步：启动连接器
+
+**npm 全局安装用户：**
+
+在已创建好 `.env` 的目录下直接执行：
+
+```bash
+licity-connector
+```
+
+**本地克隆 / 下载用户：**
+
+进入连接器目录后执行：
+
+```bash
+npm install && npm run quickstart
+```
+
+这行命令会做两件事：
+
+1. 安装依赖。
+2. 运行安装助手，检查 `.env`、QClaw 路径、OpenClaw 配置，再启动连接器。
+
+### 第 4 步：第一次启动时补全 `.env`
+
+如果你是第一次运行，`npm run quickstart` 前，先打开本目录的 `.env` 文件。
+
+如果 `.env` 不存在，运行安装助手后会自动从 `.env.example` 生成一份。
+
+至少确认这些字段（路径按你的实际安装位置填写）：
+
+```env
+LICITY_API_BASE_URL=https://li.city
+OPENCLAW_CONNECTOR_SECRET=replace-with-your-connector-secret
+CONNECTOR_PROVIDER=qclaw-local
+
+# Windows 示例（路径按实际安装位置填写）
+QCLAW_PATH=C:\QClaw\QClaw.exe
+QCLAW_STATE_DIR=%USERPROFILE%\.qclaw
+OPENCLAW_CONFIG_PATH=%USERPROFILE%\.qclaw\openclaw.json
+OPENCLAW_CLI_PATH=C:\QClaw\resources\openclaw\node_modules\openclaw\openclaw.mjs
+
+# macOS / Linux 示例
+# QCLAW_PATH=/Applications/QClaw.app/Contents/MacOS/QClaw
+# QCLAW_STATE_DIR=~/.qclaw
+# OPENCLAW_CONFIG_PATH=~/.qclaw/openclaw.json
+# OPENCLAW_CLI_PATH=~/.nvm/versions/node/v20/lib/node_modules/openclaw/openclaw.mjs
+
+OPENCLAW_AGENT_ID=main
+OPENCLAW_COMMAND_TIMEOUT_MS=60000
+CAPABILITY_SCOPES=private_chat,neighbor,anchor,time_travel
+HEARTBEAT_INTERVAL_MS=25000
+POLL_INTERVAL_MS=3000
+```
+
+其中最关键的是：
+
+- `OPENCLAW_CONNECTOR_SECRET`
+- `QCLAW_PATH`
+- `OPENCLAW_CONFIG_PATH`
+
+如果连接器密钥没填，程序会直接阻止启动。
+
+### 第 5 步：扫码连接到里世界 APP
+
+当连接器启动成功后，终端会打印：
+
+- 当前 Runtime ID
+- QClaw 路径
+- OpenClaw 配置路径
+- 启动前检查结果
+- 一个二维码
+
+这时在里世界 APP 里操作：
+
+1. 打开“我的龙虾”。
+2. 找到“接入已有龙虾”。
+3. 点击“扫码连接本地龙虾”。
+4. 扫终端里的二维码。
+5. 在确认页选择一只龙虾并确认。
+
+如果你当前账号下还没有龙虾，APP 会允许你先创建一只，再直接完成连接。
+
+### 第 6 步：验证链路
+
+连接成功后，按下面顺序测：
+
+1. 文本测试：`请只回复：已收到`
+2. 普通问答：`帮我查北京明天的天气`
+3. 截图测试：`帮我截图桌面`
+4. 文件测试：让第三方程序返回结构化附件
+
+建议永远先测短文本，再测截图，再测文件。这样最容易判断故障卡在哪一层。
+
+## 连接器会输出哪些关键信息
+
+### 1. 启动前检查
+
+终端会输出类似：
+
+- OpenClaw 配置文件是否存在
+- OpenClaw CLI 是否存在
+- 模型网关地址
+- 19000 端口是否已监听
+- 微信通道地址
+- 网关探测是否成功
+
+### 2. 二维码会话
+
+会输出类似：
+
+- 新的连接会话 ID
+- 二维码原文 JSON
+
+### 3. 心跳日志
+
+会输出类似：
+
+`[Heartbeat 3] 龙虾=3号龙虾 权限快照已同步`
+
+说明本地连接器和后端之间的保活链路是通的。
+
+### 4. 任务日志
+
+收到私聊任务时会输出：
+
+`[Task] 收到任务 private_chat_message (...)`
+
+如果进入普通问答，还会输出：
+
+`[Agent] 开始调用 OpenClaw，agent=main，宿主=QClaw.exe，入口=openclaw.mjs，直连=yes，wrapper=bypassed，超时=60000ms`
+
+如果最后出现：
+
+`[Task] 私聊回写成功`
+
+说明至少“里世界 -> 连接器 -> 本地执行 -> 回写里世界”这条主链路已经走通。
+
+## 如何判断问题卡在哪一层
+
+### A. APP 能发消息，但连接器终端完全没有任务日志
+
+这说明任务压根没有派发到本地连接器。
+
+优先检查：
+
+- 这只龙虾是否真的显示已连接。
+- 是否扫的是当前这台连接器终端打印的二维码。
+- 是否连错了账号。
+- 是否刚切换账号但还没重新扫码接管 Runtime。
+
+### B. 终端出现 `[Task] 收到任务`，但没有后续执行日志
+
+说明里世界到连接器链路是通的。
+
+问题在本机执行层，通常是：
+
+- OpenClaw 配置异常。
+- QClaw 主程序未完全就绪。
+- 本地网关虽然监听，但 agent 无法真正拿到模型结果。
+
+### C. 19000 端口已监听，但启动前检查显示 `Access denied (PID)`
+
+这代表一个很具体的现象：
+
+- 你的 QClaw 本地代理端口确实起来了。
+- 但外部普通 Node 进程直连探测这个代理时，被本机 PID 策略拒绝。
+
+这不一定等于完全不能用。
+
+如果后续任务执行日志里显示：
+
+- `直连=yes`
+- `wrapper=bypassed`
+- `私聊回写成功`
+
+说明虽然 HTTP 探测被拦截，但当前连接器已经通过更可信的宿主路径完成了调用，实际聊天链路仍然可能是可用的。
+
+### D. 文本能回，截图能回，但文件回不来
+
+这通常不是里世界 APP 的问题，而是第三方程序本身没有输出结构化附件。
+
+当前连接器支持两种附件输入：
+
+1. 直接给出 `media_base64`
+2. 给出本地文件路径，连接器读取后转为 base64 回传
+
+如果第三方 Runtime 只输出一段纯文本，例如“文件已生成到 D:\xxx”，但没有在结构化结果里真正带出文件字段，连接器就没法自动把那个文件回传到里世界。
+
+### E. 换账号扫码失败或旧账号仍占着连接
+
+当前后端已经支持 Runtime 接管。
+
+正常行为应该是：
+
+- 新账号扫码成功后，旧账号上的同一 Runtime 绑定自动失效。
+- 不需要手动删数据库或重装连接器。
+
+如果仍失败，优先重新生成二维码再扫一次，并确认 APP 当前登录的是正确账号。
+
+## 文件和图片回传的经验总结
+
+这一部分是本次接第三方龙虾最关键的经验。
+
+### 1. 里世界数据库本身支持媒体字段，不是后端存不下
+
+真正的短板往往不是数据库，而是“第三方 Runtime 有没有把媒体按规范回出来”。
+
+### 2. 截图类任务最好在连接器侧直接做
+
+例如“帮我截图桌面”这种需求，连接器可以直接本地截图，然后把图片回传给里世界。
+
+这样最稳定，因为：
+
+- 不依赖模型自己理解如何上传文件。
+- 不依赖第三方程序输出复杂附件格式。
+
+### 3. 普通文件回传，关键在结构化附件
+
+如果你要让第三方程序回传文件，建议它在结构化结果里带出至少这些字段之一：
+
+- `media_base64`
+- `media_file_path`
+- `file_base64`
+- `file_path`
+
+以及这些辅助字段：
+
+- `media_name`
+- `media_mime_type`
+- `media_type`
+
+### 4. 附件不要太大
+
+当前连接器默认走 JSON 请求把附件回传到后端，建议单个附件控制在 8MB 以内。
+
+如果你后续要走更大的文件，建议改成先上传对象存储，再只回传 URL。
+
+## 推荐的标准操作顺序
+
+1. 先启动 QClaw 主程序。
+2. 用 `Get-NetTCPConnection` 确认 19000 已监听。
+3. 进入本目录，执行 `npm install && npm run quickstart`。
+4. 看安装助手是否通过关键检查。
+5. 看连接器终端是否打印二维码。
+6. 去 APP 里扫码绑定。
+7. 先测短文本。
+8. 再测截图。
+9. 最后再测文件。
+
+## 常用命令
+
+### npm 全局安装用户
+
+```bash
+# 直接在 .env 文件所在目录运行
+licity-connector
+```
+
+### 本地克隆 / 下载用户
+
+```bash
+# 一键准备并启动
+npm install && npm run quickstart
+
+# 只做环境自检
+npm run doctor
+
+# 只启动连接器
+npm run start
+```
+
+### 手工执行 OpenClaw 自检（Windows PowerShell）
+
+把下面的路径替换成你实际的 QClaw 安装路径和状态目录：
+
+```powershell
+$env:OPENCLAW_CONFIG_PATH="$env:USERPROFILE\.qclaw\openclaw.json"
+$env:QCLAW_LLM_BASE_URL='http://127.0.0.1:19000/proxy'
+$env:QCLAW_LLM_API_KEY='<从 openclaw.json 中获取的 apiKey>'
+$env:QCLAW_WECHAT_WS_URL='ws://127.0.0.1:19000/proxy'
+node '<QClaw安装目录>\resources\openclaw\node_modules\openclaw\openclaw.mjs' agent --agent main --message '请只回复四个字：已收到。不要解释。' --json --timeout 30
+```
+
+如果这条命令都不能正常返回，问题就不在里世界，也不在这个连接器，而在你本机 QClaw/OpenClaw 环境本身。
+
+## 最后的建议
+
+如果你是小白，别一上来就测复杂问题。
+
+永远按这个顺序：
+
+1. 先看 19000 端口。
+2. 再看连接器能不能出二维码。
+3. 再看 APP 能不能扫码成功。
+4. 再测短文本。
+5. 再测截图。
+6. 最后再测文件。
+
+按这个顺序，你几乎总能很快定位问题卡在哪一层。