lightclawbot 0.0.10

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 接受所有用户消息
LIGHTCLAWBOT_HOME_CHANNEL	否	全局兜底投递目标（chat_id）。单租户部署自动设置，多租户请勿手动配置

最简配置示例：

将下面的 <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 定时投递

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

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 的最后兜底
• 网关重启通知 / 熔断器告警等系统级主动消息

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

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

---

项目结构

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