npm package: @licity/qclaw-local-connector
Description: 里世界 OpenClaw 本地连接器，支持 QClaw 与其他兼容 OpenClaw CLI 的本地 Runtime 扫码接入
Latest version: 1.4.0
Deprecated: 已废弃，请使用新版: npx @licity/openclaw-connector

# 里世界 OpenClaw 本地连接器

这是里世界的本地龙虾连接器。它负责把你电脑上的 OpenClaw Runtime 接进里世界 APP，让某只龙虾真正映射到本机运行。

它已经不再要求你先手填全局密钥。现在的流程是：

1. 在电脑上运行一条命令。
2. 终端立即出现二维码。
3. 用里世界 APP 扫码并选择龙虾确认。
4. 连接器自动拿到本机专用令牌并保存到本地。

当前包名仍然保留为 @licity/qclaw-local-connector，是为了兼容旧用户；但从能力上，它已经是通用 OpenClaw 连接器，不再只限 QClaw。

## 适用范围

适合以下场景：

- 你使用 QClaw，且本机带有 OpenClaw CLI。
- 你使用其他兼容 OpenClaw CLI 的本地 Runtime。
- 你希望把本机 AI 能力映射成里世界里的龙虾，由 APP 给龙虾发消息，本机 Runtime 回复。

不适合以下场景：

- 你只是要做 MCP 直连工具调用，不需要把本机 Runtime 映射成龙虾。
- 你手里的官方 Runtime 已经内置里世界原生扫码绑定，并不需要桥接器。

## 一条命令启动

无需全局安装时，可以直接运行：

```bash
npx @licity/qclaw-local-connector
```

如果你希望长期使用，也可以全局安装：

```bash
npm install -g @licity/qclaw-local-connector
```

安装后可使用以下任一命令：

```bash
licity-connector
```

```bash
licity-openclaw-connector
```

## 零密钥扫码流程

第一次运行时：

- 当前目录没有 .env，程序会自动生成一份可选模板。
- 程序不会因为未填写 OPENCLAW_CONNECTOR_SECRET 而退出。
- 程序会直接创建扫码会话并显示二维码。

扫码成功后：

- 服务端会向这台电脑下发专用 connector token。
- token 会自动写入当前工作目录下的 .licity-connector/runtime.json。
- 后续心跳、拉任务、结果回写都会自动使用这个 token。

这意味着你不再需要从 APP 手动复制连接密钥，也不需要手动把密钥填进 .env。

## 最短使用步骤

### 1. 先确认本机 Runtime 可用

至少要满足：

- OpenClaw 配置文件存在。
- OpenClaw CLI 可执行。
- 你的宿主 Runtime 已启动，并且本地模型/网关可访问。

如果你是 QClaw 用户，通常就是先启动 QClaw，并确认它的 OpenClaw 服务已经起来。

### 2. 在工作目录运行连接器

示例：

```bash
npx @licity/qclaw-local-connector
```

或者：

```bash
licity-openclaw-connector
```

### 3. 用里世界 APP 扫码

路径：

- 打开里世界 APP
- 进入“我的龙虾”
- 点击“扫码连接本地龙虾”
- 扫描终端二维码
- 选择一只龙虾并确认绑定

### 4. 验证连接

先发一句最短文本，例如：

- 请只回复：已收到

文本正常后，再测试截图或文件能力。

## .env 说明

.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 | 功能域 |

### 兼容旧字段

如果你以前已经写过以下字段，不需要重配，仍然兼容：

- QCLAW_PATH
- QCLAW_STATE_DIR
- QCLAW_CONFIG_PATH
- OPENCLAW_CONNECTOR_SECRET
- QCLAW_LLM_BASE_URL
- QCLAW_LLM_API_KEY
- QCLAW_WECHAT_WS_URL

## QClaw 用户说明

如果你使用的是 QClaw：

- 可以继续沿用现有安装路径和 .qclaw 目录。
- 连接器会自动优先兼容 QClaw 的 wrapper、qclaw.json 和网关配置。
- 包名虽然还是 qclaw-local-connector，但现在推荐你把它理解成“OpenClaw 通用连接器”。

## 其他 Runtime 用户说明

如果你不是 QClaw，而是其他兼容 OpenClaw CLI 的宿主：

- 重点保证 OPENCLAW_CONFIG_PATH 和 OPENCLAW_CLI_PATH 正确。
- 如宿主没有 qclaw.json，也不影响扫码连接。
- 如宿主网关不走 QClaw 变量，可直接设置：
  - OPENCLAW_GATEWAY_BASE_URL
  - OPENCLAW_GATEWAY_API_KEY
  - OPENCLAW_WECHAT_WS_URL

## 当前能力

已经打通：

- 扫码绑定
- 心跳保活
- 私聊文本回复
- 截图回传
- 图片 / 文件结构化回传
- 重新扫码接管旧连接

## 常见问题

### 1. 终端里出现二维码后，APP 扫码失败

先检查：

- 服务器地址是否能访问
- 终端二维码是否是最新生成的
- 是否有旧连接器实例占着同一个 runtimeId

### 2. 连接成功但龙虾不回复

优先检查：

- 本机 Runtime 是否真的启动
- OpenClaw CLI 是否可执行
- 本地模型/网关端口是否已监听

### 3. 以前必须填的 OPENCLAW_CONNECTOR_SECRET 现在还要填吗

通常不需要。

它现在只作为旧版兼容字段保留。正常扫码绑定流程下，连接器会自动拿到本机专用 token。

## 发布说明

当前推荐安装源仍然是：

```bash
npm install -g @licity/qclaw-local-connector
```

这是兼容升级，不是废弃重发。旧用户无需改包名，新的教程和命令会直接按 OpenClaw 通用连接器来写。