@licity/qclaw-local-connector 1.3.2 → 1.4.0

package/.env.example

@@ -1,14 +1,83 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# 里世界 OpenClaw 本地连接器 · .env 配置文件
+# 用任意文本编辑器（如记事本）打开，按说明填写后保存，重新运行 licity-connector。
+# 带【勿改】标记的字段直接保留默认值；带【必填】的必须根据你的电脑情况修改。
+# ──────────────────────────────────────────────────────────────────────────────
+
+# 【勿改】里世界服务器地址，固定不动。
 LICITY_API_BASE_URL=https://li.city
-OPENCLAW_CONNECTOR_SECRET=replace-with-your-connector-secret
-CONNECTOR_PROVIDER=qclaw-local
+
+# 【可选】旧版连接器验证密钥。
+# 新版推荐直接留空：首次运行会先显示二维码，扫码通过后自动下发并保存本机连接令牌。
+# 只有你要兼容旧版脚本或手动调用受保护接口时，才需要填写这个全局密钥。
+OPENCLAW_CONNECTOR_SECRET=
+
+# 【勿改】连接器类型标识，告诉里世界服务器这是 OpenClaw 本地连接器，固定不动。
+CONNECTOR_PROVIDER=openclaw-local
+
+# 【可选】这台电脑的别名，多台电脑接入时方便区分。
+# 留空时自动使用电脑的主机名（hostname）。可以填中文，例如：我的台式机
 DEVICE_NAME=
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Runtime 路径相关（以下字段优先兼容 OpenClaw，也兼容 QClaw）
+# ──────────────────────────────────────────────────────────────────────────────
+
+# 【可选】宿主 Runtime 主程序（.exe）完整路径。
+# 如果你使用 QClaw，可直接填 QClaw 主程序路径；其他宿主可填其实际启动文件。
+OPENCLAW_RUNTIME_PATH=D:\QClaw\QClaw.exe
+
+# 兼容旧版字段。若你已经在用 QCLAW_PATH，可继续保留。
 QCLAW_PATH=D:\QClaw\QClaw.exe
+
+# 【必填】OpenClaw / 宿主 Runtime 的状态目录（存放配置文件、登录状态等）。
+# ⚠️ 必须把 Administrator 改成你电脑的 Windows 用户名（中文名也可以）！
+# 怎么查用户名：按 Win+R → 输入 cmd 回车 → 输入 echo %USERNAME% → 回车查看。
+# 确认方法：打开文件管理器 → 地址栏输入此路径 → 能看到文件夹说明路径正确。
+OPENCLAW_STATE_DIR=C:\Users\Administrator\.qclaw
+
+# 兼容旧版字段。
 QCLAW_STATE_DIR=C:\Users\Administrator\.qclaw
+
+# 【可选】宿主 Runtime 主配置文件路径。
+# QClaw 用户可继续填写 qclaw.json，其他宿主没有这个文件也不影响扫码连接。
 QCLAW_CONFIG_PATH=C:\Users\Administrator\.qclaw\qclaw.json
+
+# 【必填】OpenClaw（QClaw 内置 AI 框架）的配置文件路径。
+# 值 = QCLAW_STATE_DIR 后面加 \openclaw.json，把 Administrator 改成你的用户名即可。
+# 这个文件由 QClaw 自动维护，正常情况下只读不写。
 OPENCLAW_CONFIG_PATH=C:\Users\Administrator\.qclaw\openclaw.json
+
+# 【必填】OpenClaw 命令行程序（.mjs）的完整路径。
+# 连接器通过这个程序直接调用 QClaw 的 AI 能力来执行任务。
+# 路径格式固定：「QClaw 安装目录」\resources\openclaw\node_modules\openclaw\openclaw.mjs
+# 把开头的 D:\QClaw 改成你的 QClaw 实际安装目录，后面的路径不变。
 OPENCLAW_CLI_PATH=D:\QClaw\resources\openclaw\node_modules\openclaw\openclaw.mjs
+
+# ──────────────────────────────────────────────────────────────────────────────
+# 以下为可选配置项，默认值通常够用，不需要改动
+# ──────────────────────────────────────────────────────────────────────────────
+
+# 【勿改】使用 OpenClaw 的哪个 Agent 执行任务，通常固定填 main。
 OPENCLAW_AGENT_ID=main
+
+# 【可选】如果你不是通过 QClaw 网关提供模型能力，也可以直接指定 OpenClaw 网关地址与鉴权。
+OPENCLAW_GATEWAY_BASE_URL=
+OPENCLAW_GATEWAY_API_KEY=
+OPENCLAW_WECHAT_WS_URL=
+
+# 【可选】AI 执行一次任务的最长等待时间（毫秒）。
+# 默认 60000 = 60 秒。如果 AI 经常超时，可以调大，例如 120000（2 分钟）。
 OPENCLAW_COMMAND_TIMEOUT_MS=60000
+
+# 【勿改】此连接器支持的功能域，不要修改。
+# private_chat=私信回复, neighbor=邻里圈, anchor=穿越锚点, time_travel=穿越
 CAPABILITY_SCOPES=private_chat,neighbor,anchor,time_travel
+
+# 【可选】连接器向里世界服务器发送心跳信号的间隔（毫秒）。
+# 默认 25000 = 25 秒。心跳用于维持龙虾「在线」状态，超过 3 分钟无心跳会标记离线。
 HEARTBEAT_INTERVAL_MS=25000
+
+# 【可选】连接器轮询是否有新任务（私信等）的频率（毫秒）。
+# 默认 3000 = 3 秒查询一次。值越小响应越快，但服务器请求也越多。
 POLL_INTERVAL_MS=3000

package/README.md

@@ -1,491 +1,204 @@
-# 里世界 QClaw 本地连接器
+# 里世界 OpenClaw 本地连接器
 
-这是把本机 QClaw 或其他第三方本地 Runtime，桥接到里世界 APP 龙虾系统的本地连接器。
+这是里世界的本地龙虾连接器。它负责把你电脑上的 OpenClaw Runtime 接进里世界 APP，让某只龙虾真正映射到本机运行。
 
-它解决的不是“让 QClaw 自己联网找里世界”，而是另一件事：
+它已经不再要求你先手填全局密钥。现在的流程是：
 
-- 在你电脑上生成一个给里世界 APP 扫描的连接二维码。
-- 扫码成功后，把某只龙虾和你这台电脑上的 Runtime 绑定起来。
-- 后续由里世界把任务派发给本地连接器，再由本地连接器转给 QClaw/OpenClaw 执行。
+1. 在电脑上运行一条命令。
+2. 终端立即出现二维码。
+3. 用里世界 APP 扫码并选择龙虾确认。
+4. 连接器自动拿到本机专用令牌并保存到本地。
 
-如果你是第一次接触这个链路，先记住一句话：
+当前包名仍然保留为 @licity/qclaw-local-connector，是为了兼容旧用户；但从能力上，它已经是通用 OpenClaw 连接器，不再只限 QClaw。
 
-只启动本目录里的连接器还不够。QClaw 主程序、本地 19000 网关、连接器扫码绑定，这三层必须同时成立。
+## 适用范围
 
-## 安装方式
+适合以下场景：
 
-### 方式一：npm 全局安装（推荐）
+- 你使用 QClaw，且本机带有 OpenClaw CLI。
+- 你使用其他兼容 OpenClaw CLI 的本地 Runtime。
+- 你希望把本机 AI 能力映射成里世界里的龙虾，由 APP 给龙虾发消息，本机 Runtime 回复。
 
-**第一步：安装 Node.js**
+不适合以下场景：
 
-没有 Node.js 的需要先安装它（npm 命令附带在 Node.js 里）。
+- 你只是要做 MCP 直连工具调用，不需要把本机 Runtime 映射成龙虾。
+- 你手里的官方 Runtime 已经内置里世界原生扫码绑定，并不需要桥接器。
 
-1. 打开浏览器，访问 [nodejs.org](https://nodejs.org)
-2. 点击显示"LTS"的大按钮下载安装包（Windows 下载 `.msi` 文件）
-3. 下载完成后双击运行，一直点"Next"直到安装完成，保持所有默认选项
-4. 安装完后打开终端（见下一步），输入 `node -v`，能看到版本号说明安装成功
+## 一条命令启动
 
-**如何打开终端：**
-- **Windows 11/10**：按 `Win + X`，选择"终端"或"PowerShell"；或按 `Win + R`，输入 `cmd` 回车
-- **macOS**：按 `Cmd + 空格`，搜索"Terminal"打开
-- **或者**：在文件夹空白处右键，选择"在此处打开终端"/"在终端中打开"
+无需全局安装时，可以直接运行：
 
-**第二步：全局安装连接器**
+```bash
+npx @licity/qclaw-local-connector
+```
 
-在终端里输入以下命令并回车：
+如果你希望长期使用，也可以全局安装：
 
 ```bash
 npm install -g @licity/qclaw-local-connector
 ```
 
-等待安装完成，看到 `added X packages` 字样即成功。安装过程中出现 `WARN` 字样是正常的，不影响使用。
-
-> **⚠️ Windows PowerShell 提示"禁止运行脚本"怎么办？**
->
-> 如果出现以下错误：
-> ```
-> npm : 无法加载文件 ...npm.ps1，因为在此系统上禁止运行脚本
-> ```
-> 原因是 Windows PowerShell 默认禁止运行第三方脚本。有两个解决方案：
->
-> **方案 A（推荐）：改用 cmd 而不是 PowerShell**
-> - 按 `Win + R`，输入 `cmd` 回车，打开命令提示符（不是 PowerShell）
-> - 在 cmd 里重新运行 `npm install -g @licity/qclaw-local-connector`
->
-> **方案 B：修改 PowerShell 执行策略（需要管理员权限）**
-> - 右键点击开始菜单 → 选择"Windows PowerShell（管理员）"或"终端（管理员）"
-> - 在管理员 PowerShell 里输入：
->   ```powershell
->   Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
->   ```
-> - 按 `Y` 确认，然后重新运行安装命令
-
-**第三步：创建工作目录**
-
-在电脑上选一个记得住的文件夹作为工作目录。例如在桌面新建一个 `licity` 文件夹。
-
-> ⚠️ **重要**：不要在 npm 全局安装目录里直接运行（路径包含 `node_modules/@licity`）。请始终在你自己建的工作目录里运行。
-
-**第四步：初次运行，自动生成 `.env` 配置文件**
-
-在工作目录（例如桌面的 `licity` 文件夹）里右键 → 在此处打开终端，然后运行：
+安装后可使用以下任一命令：
 
 ```bash
 licity-connector
 ```
 
-**如果是第一次运行且当前目录没有 `.env` 文件，连接器会自动在当前目录生成一个 `.env` 模板文件，然后退出并提示你填写。**
-
-用文本编辑器打开自动生成的 `.env` 文件，按第 4 步说明填写必填项，保存后重新运行 `licity-connector` 即可。
-
-不需要手动创建 `.env` 文件 — 第一次运行会帮你生成。
-
-### 方式二：本地克隆 / 下载后运行
-
-进入连接器目录，执行：
-
 ```bash
-npm install && npm run quickstart
+licity-openclaw-connector
 ```
 
-## 一图看懂
-
-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. 本连接器已经启动，并成功和里世界中的某只龙虾完成扫码绑定。
+- 当前目录没有 .env，程序会自动生成一份可选模板。
+- 程序不会因为未填写 OPENCLAW_CONNECTOR_SECRET 而退出。
+- 程序会直接创建扫码会话并显示二维码。
 
-如果第 1 或第 2 条不满足，APP 里给龙虾发消息后，任务虽然会进入队列，但 OpenClaw agent 无法真实执行。
+扫码成功后：
 
-## 目录里有哪些文件
+- 服务端会向这台电脑下发专用 connector token。
+- token 会自动写入当前工作目录下的 .licity-connector/runtime.json。
+- 后续心跳、拉任务、结果回写都会自动使用这个 token。
 
-- `index.js`：连接器主程序。
-- `.env.example`：环境变量模板。
-- `setup.js`：本地安装助手和自检脚本。
-- `data/runtime.json`：保存本机 Runtime ID。
-- `data/screenshots/`：截图任务产生的临时图片。
+这意味着你不再需要从 APP 手动复制连接密钥，也不需要手动把密钥填进 .env。
 
-## 新手最短路径
+## 最短使用步骤
 
-### 第 1 步：启动 QClaw 主程序
+### 1. 先确认本机 Runtime 可用
 
-QClaw 的位置取决于你的安装路径，常见的在：
-- Windows：`C:\QClaw\QClaw.exe` 或安装时指定的目录
-- 也可以通过桌面快捷方式直接启动
+至少要满足：
 
-启动后不要立刻关闭，保持 QClaw 正常运行。
+- OpenClaw 配置文件存在。
+- OpenClaw CLI 可执行。
+- 你的宿主 Runtime 已启动，并且本地模型/网关可访问。
 
-### 第 2 步：确认本地 19000 端口已监听
+如果你是 QClaw 用户，通常就是先启动 QClaw，并确认它的 OpenClaw 服务已经起来。
 
-在 PowerShell 执行：
+### 2. 在工作目录运行连接器
 
-```powershell
-Get-NetTCPConnection -LocalPort 19000 -State Listen
-```
-
-如果能看到监听结果，说明 QClaw 本地网关已经起来。
-
-如果没有结果，优先检查：
-
-- QClaw 是否真的已经启动。
-- QClaw 是否卡在登录页、权限弹窗、升级弹窗。
-- 刚启动时是否还没完全拉起网关，等 5 到 15 秒再查一次。
-
-### 第 3 步：启动连接器
-
-**npm 全局安装用户：**
-
-在已创建好 `.env` 的目录下直接执行：
+示例：
 
 ```bash
-licity-connector
+npx @licity/qclaw-local-connector
 ```
 
-**本地克隆 / 下载用户：**
-
-进入连接器目录后执行：
+或者：
 
 ```bash
-npm install && npm run quickstart
+licity-openclaw-connector
 ```
 
-这行命令会做两件事：
-
-1. 安装依赖。
-2. 运行安装助手，检查 `.env`、QClaw 路径、OpenClaw 配置，再启动连接器。
-
-### 第 4 步：第一次启动时补全 `.env`
-
-**方式一（npm 全局安装）用户：**
-
-不需要手动创建 `.env` 文件。第一次在工作目录运行 `licity-connector` 时，如果目录里没有 `.env`，程序会**自动生成**一份模板并退出，提示你填写。
-
-然后用记事本或任何文本编辑器打开生成的 `.env` 文件，按下面说明填写必填项，保存后重新运行 `licity-connector`。
-
-**方式二（本地克隆/下载）用户：**
-
-首次运行 `npm run quickstart` 时，安装助手会自动从 `.env.example` 生成一份 `.env` 模板，直接编辑那个文件即可。
-
----
-
-`.env` 文件的完整示例如下。复制粘贴后，按 **【必填/可选/勿改】** 说明逐行确认：
-
-```env
-# 里世界服务器地址，勿改
-LICITY_API_BASE_URL=https://li.city
-
-# 【必填】连接器验证密钥
-# 获取方式：打开里世界 APP → 我的龙虾 → 滑到底部 → 点击"复制连接密钥"按钮
-# 将复制的内容粘贴到等号后面（替换掉 replace-with-your-connector-secret）
-OPENCLAW_CONNECTOR_SECRET=replace-with-your-connector-secret
-
-# 连接器类型，勿改
-CONNECTOR_PROVIDER=qclaw-local
-
-# 【必填】QClaw 主程序路径（按你的实际安装位置填写）
-# Windows 示例：
-QCLAW_PATH=C:\QClaw\QClaw.exe
-QCLAW_STATE_DIR=C:\Users\你的用户名\.qclaw
-OPENCLAW_CONFIG_PATH=C:\Users\你的用户名\.qclaw\openclaw.json
-OPENCLAW_CLI_PATH=C:\QClaw\resources\openclaw\node_modules\openclaw\openclaw.mjs
-
-# macOS / Linux 示例（把上面 Windows 路径注释掉，取消下面几行的注释）：
-# 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` | 里世界 APP → 我的龙虾 → 底部"**复制连接密钥**"按钮 |
-| `QCLAW_PATH` | QClaw 实际安装路径（通常右键桌面图标→属性→目标可以看到） |
-
-如果 `OPENCLAW_CONNECTOR_SECRET` 没填或填错，程序会直接拒绝连接（提示"Connector 未授权"）而不会启动。
-
-### 第 5 步：扫码连接到里世界 APP
+### 3. 用里世界 APP 扫码
 
-当连接器启动成功后，终端会打印：
+路径：
 
-- 当前 Runtime ID
-- QClaw 路径
-- OpenClaw 配置路径
-- 启动前检查结果
-- 一个二维码
+- 打开里世界 APP
+- 进入“我的龙虾”
+- 点击“扫码连接本地龙虾”
+- 扫描终端二维码
+- 选择一只龙虾并确认绑定
 
-这时在里世界 APP 里操作：
+### 4. 验证连接
 
-1. 打开“我的龙虾”。
-2. 找到“接入已有龙虾”。
-3. 点击“扫码连接本地龙虾”。
-4. 扫终端里的二维码。
-5. 在确认页选择一只龙虾并确认。
+先发一句最短文本，例如：
 
-如果你当前账号下还没有龙虾，APP 会允许你先创建一只，再直接完成连接。
+- 请只回复：已收到
 
-### 第 6 步：验证链路
+文本正常后，再测试截图或文件能力。
 
-连接成功后，按下面顺序测：
+## .env 说明
 
-1. 文本测试：`请只回复：已收到`
-2. 普通问答：`帮我查北京明天的天气`
-3. 截图测试：`帮我截图桌面`
-4. 文件测试：让第三方程序返回结构化附件
+.env 现在主要是为了补充本机路径和高级选项，不再是为了手填密钥。
 
-建议永远先测短文本，再测截图，再测文件。这样最容易判断故障卡在哪一层。
+### 常用字段
 
-## 连接器会输出哪些关键信息
+| 字段 | 说明 |
+| --- | --- |
+| LICITY_API_BASE_URL | 服务器地址，通常保持 https://li.city |
+| CONNECTOR_PROVIDER | 默认 openclaw-local，通常无需修改 |
+| DEVICE_NAME | 当前电脑别名，扫码确认页会显示 |
+| OPENCLAW_RUNTIME_PATH | 宿主 Runtime 主程序路径 |
+| OPENCLAW_STATE_DIR | OpenClaw 状态目录 |
+| OPENCLAW_CONFIG_PATH | OpenClaw 配置文件路径 |
+| OPENCLAW_CLI_PATH | OpenClaw CLI 路径 |
+| OPENCLAW_AGENT_ID | 默认 main |
+| OPENCLAW_COMMAND_TIMEOUT_MS | 单次任务超时 |
+| CAPABILITY_SCOPES | 功能域 |
 
-### 1. 启动前检查
+### 兼容旧字段
 
-终端会输出类似：
+如果你以前已经写过以下字段，不需要重配，仍然兼容：
 
-- OpenClaw 配置文件是否存在
-- OpenClaw CLI 是否存在
-- 模型网关地址
-- 19000 端口是否已监听
-- 微信通道地址
-- 网关探测是否成功
+- QCLAW_PATH
+- QCLAW_STATE_DIR
+- QCLAW_CONFIG_PATH
+- OPENCLAW_CONNECTOR_SECRET
+- QCLAW_LLM_BASE_URL
+- QCLAW_LLM_API_KEY
+- QCLAW_WECHAT_WS_URL
 
-### 2. 二维码会话
+## QClaw 用户说明
 
-会输出类似：
+如果你使用的是 QClaw：
 
-- 新的连接会话 ID
-- 二维码原文 JSON
+- 可以继续沿用现有安装路径和 .qclaw 目录。
+- 连接器会自动优先兼容 QClaw 的 wrapper、qclaw.json 和网关配置。
+- 包名虽然还是 qclaw-local-connector，但现在推荐你把它理解成“OpenClaw 通用连接器”。
 
-### 3. 心跳日志
+## 其他 Runtime 用户说明
 
-会输出类似：
+如果你不是 QClaw，而是其他兼容 OpenClaw CLI 的宿主：
 
-`[Heartbeat 3] 龙虾=3号龙虾 权限快照已同步`
+- 重点保证 OPENCLAW_CONFIG_PATH 和 OPENCLAW_CLI_PATH 正确。
+- 如宿主没有 qclaw.json，也不影响扫码连接。
+- 如宿主网关不走 QClaw 变量，可直接设置：
+  - OPENCLAW_GATEWAY_BASE_URL
+  - OPENCLAW_GATEWAY_API_KEY
+  - OPENCLAW_WECHAT_WS_URL
 
-说明本地连接器和后端之间的保活链路是通的。
+## 当前能力
 
-### 4. 任务日志
+已经打通：
 
-收到私聊任务时会输出：
+- 扫码绑定
+- 心跳保活
+- 私聊文本回复
+- 截图回传
+- 图片 / 文件结构化回传
+- 重新扫码接管旧连接
 
-`[Task] 收到任务 private_chat_message (...)`
+## 常见问题
 
-如果进入普通问答，还会输出：
+### 1. 终端里出现二维码后，APP 扫码失败
 
-`[Agent] 开始调用 OpenClaw，agent=main，宿主=QClaw.exe，入口=openclaw.mjs，直连=yes，wrapper=bypassed，超时=60000ms`
+先检查：
 
-如果最后出现：
+- 服务器地址是否能访问
+- 终端二维码是否是最新生成的
+- 是否有旧连接器实例占着同一个 runtimeId
 
-`[Task] 私聊回写成功`
-
-说明至少“里世界 -> 连接器 -> 本地执行 -> 回写里世界”这条主链路已经走通。
-
-## 如何判断问题卡在哪一层
-
-### A. APP 能发消息，但连接器终端完全没有任务日志
-
-这说明任务压根没有派发到本地连接器。
+### 2. 连接成功但龙虾不回复
 
 优先检查：
 
-- 这只龙虾是否真的显示已连接。
-- 是否扫的是当前这台连接器终端打印的二维码。
-- 是否连错了账号。
-- 是否刚切换账号但还没重新扫码接管 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 有没有把媒体按规范回出来”。
+- 本机 Runtime 是否真的启动
+- OpenClaw CLI 是否可执行
+- 本地模型/网关端口是否已监听
 
-### 2. 截图类任务最好在连接器侧直接做
+### 3. 以前必须填的 OPENCLAW_CONNECTOR_SECRET 现在还要填吗
 
-例如“帮我截图桌面”这种需求，连接器可以直接本地截图，然后把图片回传给里世界。
+通常不需要。
 
-这样最稳定，因为：
+它现在只作为旧版兼容字段保留。正常扫码绑定流程下，连接器会自动拿到本机专用 token。
 
-- 不依赖模型自己理解如何上传文件。
-- 不依赖第三方程序输出复杂附件格式。
+## 发布说明
 
-### 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
+npm install -g @licity/qclaw-local-connector
 ```
 
-如果这条命令都不能正常返回，问题就不在里世界，也不在这个连接器，而在你本机 QClaw/OpenClaw 环境本身。
-
-## 最后的建议
-
-如果你是小白，别一上来就测复杂问题。
-
-永远按这个顺序：
-
-1. 先看 19000 端口。
-2. 再看连接器能不能出二维码。
-3. 再看 APP 能不能扫码成功。
-4. 再测短文本。
-5. 再测截图。
-6. 最后再测文件。
-
-按这个顺序，你几乎总能很快定位问题卡在哪一层。
+这是兼容升级，不是废弃重发。旧用户无需改包名，新的教程和命令会直接按 OpenClaw 通用连接器来写。

package/index.js

@@ -17,17 +17,47 @@ require('dotenv').config({ path: fs.existsSync(envFromCwd) ? envFromCwd : envFro
 
 const pkg = require('./package.json');
 
+function findFirstExistingPath(candidates, fallback = '') {
+  for (const candidate of candidates) {
+    const resolved = String(candidate || '').trim();
+    if (resolved && fs.existsSync(resolved)) {
+      return resolved;
+    }
+  }
+  return String(fallback || '').trim();
+}
+
+const detectedRuntimePath = findFirstExistingPath(
+  [
+    process.env.OPENCLAW_RUNTIME_PATH,
+    process.env.QCLAW_PATH,
+    'D:\\QClaw\\QClaw.exe',
+    'C:\\QClaw\\QClaw.exe',
+  ],
+  process.env.OPENCLAW_RUNTIME_PATH || process.env.QCLAW_PATH || 'D:\\QClaw\\QClaw.exe'
+);
+const detectedRuntimeStateDir = findFirstExistingPath(
+  [
+    process.env.OPENCLAW_STATE_DIR,
+    process.env.QCLAW_STATE_DIR,
+    path.join(os.homedir(), '.qclaw'),
+    process.env.USERPROFILE ? path.join(process.env.USERPROFILE, '.qclaw') : '',
+  ],
+  path.join(os.homedir(), '.qclaw')
+);
+
 const apiBaseUrl = String(process.env.LICITY_API_BASE_URL || 'https://li.city').replace(/\/$/, '');
 const connectorKey = String(process.env.OPENCLAW_CONNECTOR_SECRET || '').trim();
-const provider = String(process.env.CONNECTOR_PROVIDER || 'qclaw-local').trim();
+const provider = String(process.env.CONNECTOR_PROVIDER || 'openclaw-local').trim();
 const deviceName = String(process.env.DEVICE_NAME || os.hostname()).trim();
-const qclawPath = String(process.env.QCLAW_PATH || 'D:\\QClaw\\QClaw.exe').trim();
-const qclawInstallDir = path.dirname(qclawPath);
-const qclawCliWrapperPath = path.join(qclawInstallDir, 'resources', 'openclaw', 'config', 'skills', 'qclaw-openclaw', 'scripts', 'openclaw-win.cmd');
-const qclawStateDir = String(process.env.QCLAW_STATE_DIR || path.join(os.homedir(), '.qclaw')).trim();
-const qclawConfigPath = String(process.env.QCLAW_CONFIG_PATH || path.join(qclawStateDir, 'qclaw.json')).trim();
-const openclawConfigPath = String(process.env.OPENCLAW_CONFIG_PATH || path.join(qclawStateDir, 'openclaw.json')).trim();
-const openclawCliPath = String(process.env.OPENCLAW_CLI_PATH || path.join(qclawInstallDir, 'resources', 'openclaw', 'node_modules', 'openclaw', 'openclaw.mjs')).trim();
+const runtimePath = String(detectedRuntimePath).trim();
+const runtimeInstallDir = path.dirname(runtimePath);
+const runtimeDisplayName = String(process.env.OPENCLAW_RUNTIME_NAME || 'OpenClaw Runtime').trim();
+const qclawCliWrapperPath = path.join(runtimeInstallDir, 'resources', 'openclaw', 'config', 'skills', 'qclaw-openclaw', 'scripts', 'openclaw-win.cmd');
+const runtimeStateDir = String(detectedRuntimeStateDir).trim();
+const qclawConfigPath = String(process.env.QCLAW_CONFIG_PATH || path.join(runtimeStateDir, 'qclaw.json')).trim();
+const openclawConfigPath = String(process.env.OPENCLAW_CONFIG_PATH || path.join(runtimeStateDir, 'openclaw.json')).trim();
+const openclawCliPath = String(process.env.OPENCLAW_CLI_PATH || path.join(runtimeInstallDir, 'resources', 'openclaw', 'node_modules', 'openclaw', 'openclaw.mjs')).trim();
 const openclawAgentId = String(process.env.OPENCLAW_AGENT_ID || 'main').trim();
 const openclawCommandTimeoutMs = Number(process.env.OPENCLAW_COMMAND_TIMEOUT_MS || 60000);
 const heartbeatIntervalMs = Number(process.env.HEARTBEAT_INTERVAL_MS || 25000);
@@ -39,38 +69,22 @@ const capabilityScopes = String(process.env.CAPABILITY_SCOPES || 'private_chat,n
   .filter(Boolean);
 const execFileAsync = promisify(execFile);
 
-if (!connectorKey) {
-  // 当工作目录没有 .env 时，自动生成模板并引导用户
-  if (!fs.existsSync(envFromCwd)) {
-    const templateDest = path.join(process.cwd(), '.env');
-    const templateContent = fs.existsSync(envExamplePath)
-      ? fs.readFileSync(envExamplePath, 'utf8')
-      : [
-          'LICITY_API_BASE_URL=https://li.city',
-          'OPENCLAW_CONNECTOR_SECRET=',
-          'QCLAW_PATH=C:\\QClaw\\QClaw.exe',
-          `QCLAW_STATE_DIR=${path.join(os.homedir(), '.qclaw')}`,
-          `OPENCLAW_CONFIG_PATH=${path.join(os.homedir(), '.qclaw', 'openclaw.json')}`,
-        ].join('\n') + '\n';
-    fs.writeFileSync(templateDest, templateContent, 'utf8');
-    console.error('');
-    console.error('══════════════════════════════════════════════════════');
-    console.error('  首次运行：已在当前目录生成 .env 配置文件模板');
-    console.error(`  文件位置：${templateDest}`);
-    console.error('');
-    console.error('  请用文本编辑器打开 .env，填写以下必填项：');
-    console.error('    OPENCLAW_CONNECTOR_SECRET  — 从里世界 APP「我的龙虾」页');
-    console.error('                                  复制「连接密钥」后粘贴到这里');
-    console.error('    QCLAW_PATH                 — QClaw 主程序实际路径');
-    console.error('    QCLAW_STATE_DIR            — QClaw 数据目录（含用户名）');
-    console.error('');
-    console.error('  填写完毕后在同一目录重新运行：licity-connector');
-    console.error('══════════════════════════════════════════════════════');
-    console.error('');
-  } else {
-    console.error('缺少 OPENCLAW_CONNECTOR_SECRET，请在当前目录的 .env 文件中填写连接密钥。');
-  }
-  process.exit(1);
+if (!fs.existsSync(envFromCwd)) {
+  const templateDest = path.join(process.cwd(), '.env');
+  const templateContent = (fs.existsSync(envExamplePath)
+    ? fs.readFileSync(envExamplePath, 'utf8')
+    : '')
+    .replace(/OPENCLAW_RUNTIME_PATH=.*/g, `OPENCLAW_RUNTIME_PATH=${runtimePath || 'D:\\QClaw\\QClaw.exe'}`)
+    .replace(/QCLAW_PATH=.*/g, `QCLAW_PATH=${runtimePath || 'D:\\QClaw\\QClaw.exe'}`)
+    .replace(/OPENCLAW_STATE_DIR=.*/g, `OPENCLAW_STATE_DIR=${runtimeStateDir}`)
+    .replace(/QCLAW_STATE_DIR=.*/g, `QCLAW_STATE_DIR=${runtimeStateDir}`)
+    .replace(/QCLAW_CONFIG_PATH=.*/g, `QCLAW_CONFIG_PATH=${qclawConfigPath}`)
+    .replace(/OPENCLAW_CONFIG_PATH=.*/g, `OPENCLAW_CONFIG_PATH=${openclawConfigPath}`)
+    .replace(/OPENCLAW_CLI_PATH=.*/g, `OPENCLAW_CLI_PATH=${openclawCliPath}`);
+  fs.writeFileSync(templateDest, templateContent, 'utf8');
+  console.log(`首次运行已在当前目录生成可选 .env: ${templateDest}`);
+  console.log('未填写 OPENCLAW_CONNECTOR_SECRET 也可以继续：程序会先出二维码，扫码通过后自动保存本机连接令牌。');
+  console.log('');
 }
 
 const state = {
@@ -80,6 +94,7 @@ const state = {
   currentSessionId: null,
   currentLobster: null,
   heartbeatCount: 0,
+  connectorToken: '',
 };
 
 // 全局安装时数据目录在运行目录下，本地开发时在包目录的 data/
@@ -89,32 +104,53 @@ const dataDir = isGlobalInstall
   : path.join(__dirname, 'data');
 const runtimeFile = path.join(dataDir, 'runtime.json');
 
-function ensureRuntimeId() {
+function readRuntimeState() {
   fs.mkdirSync(dataDir, { recursive: true });
 
   if (fs.existsSync(runtimeFile)) {
     try {
-      const saved = JSON.parse(fs.readFileSync(runtimeFile, 'utf8'));
-      if (saved && typeof saved.runtimeId === 'string' && saved.runtimeId.trim()) {
-        return saved.runtimeId.trim();
-      }
+      return JSON.parse(fs.readFileSync(runtimeFile, 'utf8')) || {};
     } catch (error) {
-      console.warn('读取本地 runtime.json 失败，将重新生成 runtimeId。');
+      console.warn('读取本地 runtime.json 失败，将重新生成本地运行状态。');
     }
   }
 
-  const runtimeId = crypto.randomUUID();
-  fs.writeFileSync(runtimeFile, JSON.stringify({ runtimeId, createdAt: new Date().toISOString() }, null, 2));
-  return runtimeId;
+  return {};
+}
+
+function writeRuntimeState(runtimeState) {
+  fs.mkdirSync(dataDir, { recursive: true });
+  fs.writeFileSync(runtimeFile, JSON.stringify(runtimeState, null, 2));
+}
+
+const runtimeState = readRuntimeState();
+if (!runtimeState.runtimeId || !String(runtimeState.runtimeId).trim()) {
+  runtimeState.runtimeId = crypto.randomUUID();
+}
+if (!runtimeState.createdAt) {
+  runtimeState.createdAt = new Date().toISOString();
+}
+writeRuntimeState(runtimeState);
+
+function persistConnectorToken(token) {
+  runtimeState.connectorToken = String(token || '').trim();
+  runtimeState.updatedAt = new Date().toISOString();
+  writeRuntimeState(runtimeState);
+  state.connectorToken = runtimeState.connectorToken;
 }
 
-const runtimeId = ensureRuntimeId();
+const runtimeId = String(runtimeState.runtimeId).trim();
+state.connectorToken = String(runtimeState.connectorToken || '').trim();
 const screenshotDir = path.join(dataDir, 'screenshots');
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function sha256(value) {
+  return crypto.createHash('sha256').update(String(value || '')).digest('hex');
+}
+
 function ensureDir(dirPath) {
   fs.mkdirSync(dirPath, { recursive: true });
 }
@@ -147,21 +183,25 @@ function toWebSocketUrl(rawUrl) {
 function buildOpenClawChildEnv() {
   const qclawConfig = readJsonFileIfExists(qclawConfigPath) || {};
   const openclawConfig = readJsonFileIfExists(openclawConfigPath) || {};
-  const qclawGatewayBaseUrl = String(qclawConfig.authGatewayBaseUrl || '').trim();
+  const qclawGatewayBaseUrl = String(qclawConfig.authGatewayBaseUrl || openclawConfig.authGatewayBaseUrl || '').trim();
   const gatewayToken = String(openclawConfig?.gateway?.auth?.token || '').trim();
-  const modelBaseUrl = String(process.env.QCLAW_LLM_BASE_URL || qclawGatewayBaseUrl).trim();
-  const modelApiKey = String(process.env.QCLAW_LLM_API_KEY || gatewayToken).trim();
-  const wechatWsUrl = String(process.env.QCLAW_WECHAT_WS_URL || toWebSocketUrl(qclawGatewayBaseUrl)).trim();
+  const modelBaseUrl = String(process.env.OPENCLAW_GATEWAY_BASE_URL || process.env.OPENCLAW_LLM_BASE_URL || process.env.QCLAW_LLM_BASE_URL || qclawGatewayBaseUrl).trim();
+  const modelApiKey = String(process.env.OPENCLAW_GATEWAY_API_KEY || process.env.OPENCLAW_LLM_API_KEY || process.env.QCLAW_LLM_API_KEY || gatewayToken).trim();
+  const wechatWsUrl = String(process.env.OPENCLAW_WECHAT_WS_URL || process.env.QCLAW_WECHAT_WS_URL || toWebSocketUrl(qclawGatewayBaseUrl)).trim();
 
   return {
     ...process.env,
     OPENCLAW_CONFIG_PATH: openclawConfigPath,
-    OPENCLAW_STATE_DIR: qclawStateDir,
+    OPENCLAW_STATE_DIR: runtimeStateDir,
     OPENCLAW_NIX_MODE: '1',
     NODE_OPTIONS: '--no-warnings',
+    ...(runtimePath ? { OPENCLAW_RUNTIME_PATH: runtimePath } : {}),
     ...(modelBaseUrl ? { QCLAW_LLM_BASE_URL: modelBaseUrl } : {}),
     ...(modelApiKey ? { QCLAW_LLM_API_KEY: modelApiKey } : {}),
     ...(wechatWsUrl ? { QCLAW_WECHAT_WS_URL: wechatWsUrl } : {}),
+    ...(modelBaseUrl ? { OPENCLAW_LLM_BASE_URL: modelBaseUrl } : {}),
+    ...(modelApiKey ? { OPENCLAW_LLM_API_KEY: modelApiKey } : {}),
+    ...(wechatWsUrl ? { OPENCLAW_WECHAT_WS_URL: wechatWsUrl } : {}),
   };
 }
 
@@ -267,13 +307,22 @@ async function runPreflightChecks() {
 
 async function requestJson(endpoint, options = {}) {
   const url = `${apiBaseUrl}${endpoint}`;
+  const headers = {
+    'Content-Type': 'application/json',
+    ...(options.headers || {}),
+  };
+
+  if (!options.allowAnonymous) {
+    if (connectorKey) {
+      headers['x-connector-key'] = connectorKey;
+    } else if (state.connectorToken) {
+      headers['x-connector-token'] = state.connectorToken;
+    }
+  }
+
   const response = await fetch(url, {
     method: options.method || 'GET',
-    headers: {
-      'Content-Type': 'application/json',
-      'x-connector-key': connectorKey,
-      ...(options.headers || {}),
-    },
+    headers,
     body: options.body ? JSON.stringify(options.body) : undefined,
   });
 
@@ -299,13 +348,15 @@ async function requestJson(endpoint, options = {}) {
 
 function printBanner() {
   console.log('========================================');
-  console.log('  里世界 QClaw 本地龙虾 Connector');
+  console.log('  里世界 OpenClaw 本地龙虾 Connector');
   console.log('========================================');
   console.log(`API: ${apiBaseUrl}`);
   console.log(`Provider: ${provider}`);
   console.log(`Runtime ID: ${runtimeId}`);
   console.log(`设备名: ${deviceName}`);
-  console.log(`QClaw 路径: ${qclawPath}`);
+  console.log(`鉴权模式: ${connectorKey ? '兼容旧版密钥' : (state.connectorToken ? '本机扫码令牌' : '首次扫码自动授权')}`);
+  console.log(`Runtime: ${runtimeDisplayName}`);
+  console.log(`Runtime 路径: ${runtimePath}`);
   console.log(`OpenClaw 配置: ${openclawConfigPath}`);
   console.log(`能力域: ${capabilityScopes.join(', ') || '无'}`);
   console.log('命令: 输入 r 重新生成二维码，输入 s 查看状态，输入 q 退出');
@@ -330,10 +381,10 @@ function printPreflightResult(preflight) {
     }
   }
   if (preflight.modelPort && !preflight.modelPortReady) {
-    console.log('! 检测到本地模型端口未启动。仅启动连接器不够，还需要先启动 QClaw 主程序并保持其本地网关可用。');
+    console.log(`! 检测到本地模型端口未启动。仅启动连接器不够，还需要先启动 ${runtimeDisplayName} 并保持其本地网关可用。`);
   }
   if (preflight.gatewayProbe?.message && String(preflight.gatewayProbe.message).includes('Access denied (PID)')) {
-    console.log('! 当前连接器进程访问 QClaw 模型代理时被本机 PID 策略拒绝。');
+    console.log(`! 当前连接器进程访问 ${runtimeDisplayName} 模型代理时被本机 PID 策略拒绝。`);
     console.log('! 这说明端口虽然已监听，但普通问答任务仍无法由外部 node 进程真正执行。');
   }
   console.log('');
@@ -607,13 +658,13 @@ async function runOpenClawAgent(task) {
           '--timeout',
           String(Math.max(15, Math.ceil(openclawCommandTimeoutMs / 1000))),
         ], {
-          cwd: qclawStateDir,
+          cwd: runtimeStateDir,
           env: childEnv,
           windowsHide: true,
           stdio: ['ignore', 'pipe', 'pipe'],
         })
       : spawn(command, args, {
-          cwd: qclawStateDir,
+          cwd: runtimeStateDir,
           env: childEnv,
           windowsHide: true,
           stdio: ['ignore', 'pipe', 'pipe'],
@@ -731,9 +782,12 @@ async function createScanSession() {
   state.currentSessionId = null;
   state.currentLobster = null;
   state.heartbeatCount = 0;
+  const pollToken = crypto.randomUUID();
+  state.currentPollToken = pollToken;
 
   return requestJson('/api/openclaw/scan-session', {
     method: 'POST',
+    allowAnonymous: true,
     body: {
       runtimeId,
       provider,
@@ -742,9 +796,10 @@ async function createScanSession() {
       version: pkg.version,
       capabilityScopes,
       metadata: {
-        connector: 'licity-qclaw-local-connector',
+        connector: 'licity-openclaw-local-connector',
         nodeVersion: process.version,
-        qclawPath,
+        runtimePath,
+        pollTokenHash: sha256(pollToken),
       },
     },
   });
@@ -753,12 +808,19 @@ async function createScanSession() {
 async function waitForApproval(sessionId) {
   state.mode = 'waiting-approval';
   state.currentSessionId = sessionId;
+  const pollToken = state.currentPollToken;
 
   while (state.shouldRun && !state.reconnectRequested) {
-    const result = await requestJson(`/api/openclaw/scan-session/${sessionId}`);
+    const result = await requestJson(
+      `/api/openclaw/scan-session/${sessionId}?pollToken=${encodeURIComponent(pollToken)}`,
+      { allowAnonymous: true }
+    );
     const session = result.session;
 
     if (session.status === 'approved') {
+      if (session.connectorAuthToken) {
+        persistConnectorToken(session.connectorAuthToken);
+      }
       state.mode = 'connected';
       state.currentLobster = session.lobster || null;
       return session;
@@ -784,8 +846,8 @@ async function sendHeartbeat() {
     body: {
       runtimeId,
       metadata: {
-        connector: 'licity-qclaw-local-connector',
-        qclawPath,
+        connector: 'licity-openclaw-local-connector',
+        runtimePath,
         heartbeatAt: new Date().toISOString(),
       },
     },
@@ -820,7 +882,7 @@ async function emitTaskReply(task, payloadOrContent) {
         meta: {
           taskId: task.id,
           runtimeId,
-          qclawPath,
+          runtimePath,
         },
       }
     : {
@@ -829,7 +891,7 @@ async function emitTaskReply(task, payloadOrContent) {
           ...(payloadOrContent?.meta || {}),
           taskId: task.id,
           runtimeId,
-          qclawPath,
+          runtimePath,
         },
       };
 
@@ -856,7 +918,7 @@ async function handleTask(task) {
       const brief = rawContent ? rawContent.slice(0, 80) : '空消息';
       let reply = '';
       let taskResult = {
-        qclawPath,
+        runtimePath,
         openclawAgentId,
       };
 
@@ -957,6 +1019,9 @@ async function heartbeatLoop() {
       } catch (error) {
         console.error(`心跳失败: ${error.message}`);
         if (error.status === 403 || error.status === 404) {
+          if (!connectorKey) {
+            persistConnectorToken('');
+          }
           console.log('当前绑定已失效，准备重新进入扫码连接。');
           return;
         }
@@ -975,6 +1040,9 @@ async function heartbeatLoop() {
       } catch (error) {
         console.error(`拉取任务失败: ${error.message}`);
         if (error.status === 403 || error.status === 404) {
+          if (!connectorKey) {
+            persistConnectorToken('');
+          }
           console.log('当前绑定已失效，准备重新进入扫码连接。');
           return;
         }

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@licity/qclaw-local-connector",
-  "version": "1.3.2",
-  "description": "里世界龙虾本地连接器 — 把 QClaw 或其他第三方本地 Runtime 接入里世界 APP",
+  "version": "1.4.0",
+  "description": "里世界 OpenClaw 本地连接器，支持 QClaw 与其他兼容 OpenClaw CLI 的本地 Runtime 扫码接入",
   "main": "index.js",
   "bin": {
-    "licity-connector": "index.js"
+    "licity-connector": "index.js",
+    "licity-openclaw-connector": "index.js"
   },
   "files": [
     "index.js",
     "setup.js",
     ".env.example",
-    "README.md"
+    "README.md",
+    "启动里世界OpenClaw连接器.bat"
   ],
   "scripts": {
     "setup": "node setup.js",
@@ -22,6 +24,7 @@
     "licity",
     "qclaw",
     "openclaw",
+    "runtime",
     "connector",
     "lobster",
     "local-connector"

package/setup.js

@@ -27,6 +27,16 @@ function ensureDir(dirPath) {
   fs.mkdirSync(dirPath, { recursive: true });
 }
 
+function findFirstExistingPath(candidates, fallback = '') {
+  for (const candidate of candidates) {
+    const resolved = String(candidate || '').trim();
+    if (resolved && fs.existsSync(resolved)) {
+      return resolved;
+    }
+  }
+  return String(fallback || '').trim();
+}
+
 function ensureEnvFile() {
   if (fs.existsSync(envPath)) {
     return false;
@@ -47,32 +57,33 @@ function main() {
   const isDoctorOnly = process.argv.includes('--doctor');
   const isPrepareOnly = process.argv.includes('--prepare-only');
 
-  console.log('里世界 QClaw 连接器安装助手');
+  console.log('里世界 OpenClaw 连接器安装助手');
   const createdEnv = ensureEnvFile();
   ensureDir(dataDir);
   ensureDir(screenshotDir);
 
   const env = readEnvFile(envPath);
-  const qclawPath = String(env.QCLAW_PATH || 'D:\\QClaw\\QClaw.exe').trim();
-  const qclawStateDir = String(env.QCLAW_STATE_DIR || path.join(os.homedir(), '.qclaw')).trim();
-  const openclawConfigPath = String(env.OPENCLAW_CONFIG_PATH || path.join(qclawStateDir, 'openclaw.json')).trim();
+  const runtimePath = findFirstExistingPath(
+    [env.OPENCLAW_RUNTIME_PATH, env.QCLAW_PATH, 'D:\\QClaw\\QClaw.exe', 'C:\\QClaw\\QClaw.exe'],
+    env.OPENCLAW_RUNTIME_PATH || env.QCLAW_PATH || 'D:\\QClaw\\QClaw.exe'
+  );
+  const runtimeStateDir = findFirstExistingPath(
+    [env.OPENCLAW_STATE_DIR, env.QCLAW_STATE_DIR, path.join(os.homedir(), '.qclaw')],
+    path.join(os.homedir(), '.qclaw')
+  );
+  const openclawConfigPath = String(env.OPENCLAW_CONFIG_PATH || path.join(runtimeStateDir, 'openclaw.json')).trim();
   const connectorSecret = String(env.OPENCLAW_CONNECTOR_SECRET || '').trim();
 
-  printCheck('.env 文件', true, createdEnv ? '已按模板创建，请补全密钥后再启动' : '已存在');
+  printCheck('.env 文件', true, createdEnv ? '已按模板创建，可直接扫码授权' : '已存在');
   printCheck('数据目录', true, dataDir);
   printCheck('截图目录', true, screenshotDir);
-  printCheck('QClaw 程序路径', fs.existsSync(qclawPath), qclawPath);
+  printCheck('Runtime 程序路径', fs.existsSync(runtimePath), runtimePath);
   printCheck('OpenClaw 配置文件', fs.existsSync(openclawConfigPath), openclawConfigPath);
-  printCheck('连接器密钥', !!connectorSecret, connectorSecret ? '已配置' : '请在 .env 中填写 OPENCLAW_CONNECTOR_SECRET');
+  printCheck('连接器密钥', true, connectorSecret ? '已配置旧版兼容密钥' : '未配置，将在扫码成功后自动下发本机令牌');
 
   if (isDoctorOnly || isPrepareOnly) {
     return;
   }
-
-  if (!connectorSecret) {
-    console.log('未检测到连接器密钥，已停止。先打开 .env 填入 OPENCLAW_CONNECTOR_SECRET，再执行 npm run quickstart。');
-    process.exit(1);
-  }
 }
 
 main();

package//345/220/257/345/212/250/351/207/214/344/270/226/347/225/214OpenClaw/350/277/236/346/216/245/345/231/250.bat

@@ -0,0 +1,31 @@
+@echo off
+setlocal
+chcp 65001 >nul
+title 里世界 OpenClaw 本地连接器
+
+echo ========================================
+echo   里世界 OpenClaw 本地连接器
+echo ========================================
+echo 首次运行会自动生成 .env，并直接显示二维码。
+echo 扫码通过后会自动下发本机连接令牌，无需手填密钥。
+echo.
+
+where licity-openclaw-connector >nul 2>nul
+if %errorlevel%==0 (
+  licity-openclaw-connector
+  goto end
+)
+
+where licity-connector >nul 2>nul
+if %errorlevel%==0 (
+  licity-connector
+  goto end
+)
+
+echo 未找到连接器命令，请先执行：
+echo npm install -g @licity/qclaw-local-connector
+echo.
+pause
+
+:end
+endlocal