Metadata-Version: 2.4
Name: lightclawbot
Version: 0.0.11
Summary: LightClaw platform plugin for Hermes Agent — connects via native WebSocket to LightClaw server
Author: lhanyun
License-Expression: MIT
Keywords: hermes,hermes-agent,lightclaw,plugin,websocket,chatbot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# lightclawbot

LightClaw 平台适配器插件，为 Hermes Agent 提供通过 WebSocket 接入 LightClaw 服务端的能力，使 Hermes Agent 能与 LightClaw 用户进行实时对话、收发文件附件、发送打字指示符，以及通过 cron 定时推送消息。

```
用户(前端) ←→ LightClaw Server ←→ lightclawbot ←→ Hermes AIAgent
              (WebSocket)        (本插件，非侵入)
```

---

## 工作原理

lightclawbot 采用 Hermes Agent 的**插件注册机制**集成，**不修改主仓库任何源码**。

Hermes Agent 启动时会：
1. 通过 `config.yaml` 的 `plugins.enabled` 列表加载启用的插件；
2. 在 `~/.hermes/plugins/lightclawbot/` 下查找 `__init__.py` + `plugin.yaml`；
3. 调用插件的 `register(ctx)` 函数注册 adapter。

注册后自动获得：

- `Platform("lightclawbot")` 动态枚举成员
- gateway 启动时创建并连接 `LightClawAdapter`
- `send_message` tool 通过 `_send_via_adapter()` 路由
- cron delivery 到 `lightclawbot:<chat_id>` 自动生效
- 用户授权遵循 `LIGHTCLAW_ALLOWED_USERS` 环境变量

---

## 前置条件

| 要求 | 最低版本 |
|---|---|
| Python | 3.11+ |
| Hermes Agent | 已安装 |
| aiohttp | 3.9+（由宿主 Hermes Agent 提供） |

> 本插件不直接声明 `aiohttp` 依赖；它由宿主 Hermes Agent 环境提供。

---

## 环境变量配置

在 `~/.hermes/.env` 中设置以下变量：

| 变量 | 必填 | 说明 |
|---|---|---|
| `LIGHTCLAW_API_KEY_<UIN>` | **是** | Bearer Token，按用户 UIN 隔离（多用户共享一台实例时每人一行） |
| `LIGHTCLAW_ALLOW_ALL_USERS` | 否 | 设为 `true` 接受所有用户消息 |
| `LIGHTCLAWBOT_HOME_CHANNEL` | 否 | 全局兜底投递目标（chat_id）。单租户部署自动设置，多租户请勿手动配置 |

**最简配置示例：**

将下面的 `<UIN>` 替换为真实的用户 UIN 数字（注意：`.env` 文件**不会**展开 shell 变量，这里必须是字面量）。

```dotenv
# 单用户场景（把 100013456706 换成你的 UIN）
LIGHTCLAW_API_KEY_100013456706=your-secret-api-key

# 多用户场景（多个用户共享同一台 Hermes 实例时，每个用户一行）
LIGHTCLAW_API_KEY_100013456706=user-A-secret-api-key
LIGHTCLAW_API_KEY_100098765432=user-B-secret-api-key

LIGHTCLAW_ALLOW_ALL_USERS=true
```

---

## 启动网关

完成配置后正常启动 Hermes 网关：

```bash
hermes gateway start
```

只要 `LIGHTCLAW_API_KEY_<UIN>` 已设置（至少一行），LightClaw 适配器就会自动建立连接。日志中应出现：

```
[lightclawbot] Bot clientId: xxxx, 1 key(s) mapped
[lightclawbot] Connected (sid=xxxx)
```

---

## Cron 定时投递

### 逐用户自动投递（推荐，零配置）

LightClaw 是多租户平台，每个用户（UIN）有独立的 chat_id。**不需要**每个用户手动执行 `/sethome`，Hermes 框架会在创建定时任务时**自动记录**任务创建者的平台和 chat_id（origin 机制），投递结果时原路返回。

在 Agent 对话中创建定时任务时，推荐两种写法：

```
# 方式一：显式指定当前用户的 chat_id
每天早上 9 点发送新闻摘要。deliver=lightclawbot:123456

# 方式二：使用 origin 让框架自动路由（无需知道 chat_id）
每天早上 9 点发送新闻摘要。deliver=origin
```

Agent 内的 platform hint 会引导模型自动带上投递目标，用户无需手动操作。

### 全局兜底（仅单租户 / 系统消息）

`LIGHTCLAWBOT_HOME_CHANNEL` 是全局单值环境变量，仅在以下场景使用：

- **单租户部署**（仅 1 个 `LIGHTCLAW_API_KEY_<UIN>`）：adapter 启动时自动设置并持久化到 `.env`，无需手动配置
- 通过 API/脚本创建的、无 session 上下文的 cron job 的最后兜底
- 网关重启通知 / 熔断器告警等系统级主动消息

```dotenv
# 单租户部署时自动设置，一般无需手动配置
LIGHTCLAWBOT_HOME_CHANNEL=123456
```

> ⚠️ **多租户部署请勿手动设置 `LIGHTCLAWBOT_HOME_CHANNEL`**——这会让所有用户的定时结果都投给同一个人。
> 多租户场景下的定时投递应依赖 origin 自动回投（方式二）或显式指定 `deliver=lightclawbot:<chat_id>`（方式一）。


## 脚本
插件脚本的种类和 openclaw 插件保持一致：
- 环境检查
- 通道安装
- 升级检查
- 角色安装


## 项目结构

```
lightclawbot/
├── __init__.py             register(ctx) 插件入口
├── plugin.yaml             插件元数据（kind: platform）
└── src/                    adapter 实现
    ├── __init__.py         公开 API
    ├── adapter.py          主类 + 生命周期
    ├── config.py           常量 + 工具函数
    ├── inbound.py          入站消息处理
    ├── outbound.py         出站消息发送
    ├── history.py          历史记录/会话列表响应
    ├── media.py            媒体类型探测与格式化
    ├── file_storage.py     文件上传/下载 REST API
    ├── download_handler.py 客户端下载请求处理
    ├── tenancy.py          多租户 API key 映射
    └── socket/
        ├── native_socket.py    WebSocket 连接循环
        └── reliable_emitter.py ACK 重试发送
```

### 集成方式

lighthouse-hermes 启动时自动扫描 `~/.hermes/plugins/` 下的子目录。只要目录中同时存在：
- `__init__.py`（暴露 `register(ctx)` 函数）
- `plugin.yaml`（元数据声明 `kind: platform`）

并且在 `~/.hermes/config.yaml` 的 `plugins.enabled` 列表中列出，即可被自动发现并注册。

### 部署方式

1. **符号链接（开发环境）**：
   ```bash
   ln -s /path/to/hermes-lightclaw/hermes_lightclaw \
         ~/.hermes/plugins/lightclaw
   ```

2. **云端一键脚本（推荐）**：
   ```bash
   APIKEY="your-key" bash configure_lightclaw.sh
   ```

3. **pip install（发布后）**：
   ```bash
   pip install hermes-lightclaw
   ```
   通过 `pyproject.toml` 中的 `[project.entry-points."hermes_agent.plugins"]` 自动注册。


## 发布
lightclawbot 是发布在 `https://pypi.org/`，开发完项目后需要：
1. 更新版本号
    a. hermes-lightclaw/pyproject.toml - version
     ![Clipboard_Screenshot_1780475295.png #410px #173px](/tencent/api/attachments/s3/url?attachmentid=45987248)
    b. hermes-lightclaw/lightclawbot/plugin.yaml - version
   ![Clipboard_Screenshot_1780475350.png #608px #185px](/tencent/api/attachments/s3/url?attachmentid=45987328)
2. 执行发布流水线
     https://zhiyan.woa.com/qci/11525/pipeline/#/pipeline/detail/11739294/build/current
3. 插件发布后，前端并不会立即出现 `更新` 按钮。因为在插件升级脚本中，用的是腾讯源（`https://mirrors.tencent.com/pypi`）检查，我们的包是发布到 `PYPI` 上，需要等待腾讯源同步 PYPI（大概1小时之内）
4. 当前lighthouse镜像打包和一键升级功能，都依赖前端脚本hermes_install实现插件安装和配置。是脚本路径是写死在代码中，没有读七彩石配置。
5. 当前 ClawPro 的 Hermes Agent 镜像中，没有内置 lightclawbot，所以在AgentChat 中安装 lightclawbot，走的是 install 模式。需要推进这在镜像中内置插件，然后安装插件时，走 activate，保持和 openclaw 插件一致

## 常见问题排查

### Bot 未上线 / 收不到消息

1. 确认至少有一行 `LIGHTCLAW_API_KEY_<UIN>=...` 已设置且非空（`cat ~/.hermes/.env | grep LIGHTCLAW_API_KEY_`）
2. 确认 `config.yaml` 中 `plugins.enabled` 包含 `lightclawbot`
3. 检查网关日志中是否出现 `[lightclawbot] Connected`；若无，WebSocket 握手失败

### `aiohttp not installed`

```bash
# 在 hermes 的 venv 里安装
~/.hermes/hermes-agent/venv/bin/pip install "aiohttp>=3.9,<4"
```

### 插件未被发现

确认以下两点：

```bash
# 1. 插件目录存在且结构正确
ls ~/.hermes/plugins/lightclawbot/
# 应当看到 __init__.py 和 plugin.yaml

# 2. config.yaml 已启用
grep -A2 plugins ~/.hermes/config.yaml
# plugins:
#   enabled:
#     - lightclawbot
# platforms:
#   lightclawbot:
#     enabled: true
```

### 没有流式输出
config.yaml 已启用
```bash
# display:
#   platforms:
#     lightclawbot:
#       streaming: true
```

### hermes 升级后，插件连接不上
hermes  >= 0.15.0 版本，需要在config.yaml中添加 `platforms.lightclawbot.enabled = true`
```bash
# platforms:
#   lightclawbot:
#     enabled: true
```

### hermes 排查
通过执行 `hermes logs` 查看日志

## License

MIT
