lightclawbot 0.0.8

LightClaw platform plugin for Hermes Agent — connects via native WebSocket to LightClaw server

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 接受所有用户消息

最简配置示例：

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

# 单用户场景（把 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 网关：

hermes gateway start

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

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

---

Cron 定时投递

在 Hermes Agent 内创建定时任务时，指定 deliver 参数即可将结果推送到 LightClaw：

deliver=lightclawbot:<chat_id>

示例（在 Hermes Agent 对话中）：

每天早上 9 点发送新闻摘要。deliver=lightclawbot:123456

也可以设置全局默认投递目标：

LIGHTCLAW_HOME_CHANNEL=123456

---

项目结构

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 重试发送

---

常见问题排查

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

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

插件未被发现

确认以下两点：

# 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 已启用

# display:
#   platforms:
#     lightclawbot:
#       streaming: true

---

License

MIT