openclaw-companion

🦞 OpenClaw Companion

一个基于 Electron 的可爱龙虾桌面宠物，专为 OpenClaw 设计的 Agent Skill。当你的 AI Agent 在工作时，龙虾会在桌面上实时展示工作状态，并通过语音播报关键进展——让你不用盯着屏幕也能掌握一切。

---

✨ 功能特性

🎭 支持的状态

---

🛠️ 技术栈

• Electron — 跨平台桌面应用框架
• Canvas 2D — 纯手绘龙虾形象与动画，零外部依赖
• Express — 本地 HTTP API 服务器
• Node.js — 运行时环境

---

📦 安装

前置要求

• Node.js >= 18
• npm
• 桌面环境（显示 GUI 窗口）：Linux 需要 X11 或 Wayland，macOS/Windows 无额外要求
• 服务器/无头环境：需通过 X11 Forwarding（ssh -X）或虚拟帧缓冲（xvfb）提供显示服务

作为 OpenClaw Skill 安装

⚠️ 当前版本尚未发布到 ClawHub，请使用手动安装方式。

# 手动克隆到 skills 目录
cd ~/.openclaw/skills
git clone https://github.com/L-LesterYu/openclaw-companion.git
cd openclaw-companion
npm install

国内网络环境

国内网络环境下，npm install 和 Electron 二进制下载可能超时或失败，建议使用镜像源：

# 使用淘宝镜像安装依赖
cd ~/.openclaw/skills/openclaw-companion
npm install --registry=https://registry.npmmirror.com

# 使用 Electron 国内镜像安装二进制（如果首次安装失败）
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install electron

如果 Electron 启动时报 Electron failed to install correctly，说明二进制文件下载不完整，执行以下命令修复：

# 删除损坏的 Electron 缓存
rm -rf node_modules/electron

# 使用国内镜像重新安装（--force 确保重新下载）
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install electron --force

# 验证安装是否成功（应显示 dist 目录列表）
ls node_modules/electron/dist/

💡 如果仍然失败，可以尝试清理 npm 缓存后重试：npm cache clean --force

Plugin Hook 安装（自动状态推送）

插件会在每次工具调用后自动推送到龙虾，无需手动调用。安装步骤：

# 1. 将插件复制到 OpenClaw extensions 目录
cp -r ~/.openclaw/skills/openclaw-companion/plugin-hook ~/.openclaw/extensions/openclaw-companion-hook

# 2. 在 openclaw.json 中启用插件（如果尚未配置）
# 确保 plugins.entries 中包含：
# "openclaw-companion-hook": { "enabled": true }

# 3. 重启 Gateway 加载插件
openclaw gateway restart

# 4. 验证插件状态
openclaw plugins list  # 查看 openclaw-companion-hook 是否为 loaded

Plugin Hook 事件说明

Plugin Hook 配置项

在 openclaw.json 的 plugins.entries.openclaw-companion-hook.config 中可自定义：

{
  "apiUrl": "http://localhost:18182/api/state",
  "healthUrl": "http://localhost:18182/api/health",
  "throttleMs": 2000,
  "idleTimeoutMs": 300000,
  "enabled": true
}

---

🎮 使用方法

启动龙虾

cd ~/.openclaw/skills/openclaw-companion
npx electron . --no-sandbox

💡 --no-sandbox 参数在 Linux 服务器环境下通常必须，避免 Chromium 沙箱权限问题。macOS/Windows 桌面环境可省略。启动时如果看到 Exiting GPU process due to errors during initialization 警告，属于正常现象，不影响功能。

推送状态（手动/调试用）

Plugin Hook 已自动处理大部分状态推送，以下命令仅在特殊场景或调试时使用。

# 推送工作状态
curl -X POST http://localhost:18182/api/state \
  -H "Content-Type: application/json" \
  -d '{"state":"working","message":"正在处理...","emoji":"⌨️"}'

# 健康检查
curl http://localhost:18182/api/health

API 端点

POST /api/state 参数：

{
  "state": "working",    // 必填：idle | working | thinking | sleeping | done | error
  "message": "读取文件",  // 可选：气泡文案（建议 <20 字）
  "emoji": "📖",         // 可选：覆盖默认 emoji
  "toolName": "read",    // 可选：工具名称（供动画扩展）
  "priority": "normal"   // 可选：high | normal | low
}

---

🔊 语音播报

配合 OpenClaw 的 TTS 工具，龙虾 companion 可以语音播报关键事件：

---

📁 项目结构

openclaw-companion/
├── index.html          # 主界面（Canvas 渲染）
├── main.js             # Electron 主进程 + Express 服务器
├── preload.js          # 预加载脚本
├── package.json        # 依赖配置
├── SKILL.md            # OpenClaw Skill 描述文件
├── LICENSE             # MIT 许可证
├── sprites/            # 龙虾各状态 PNG 精灵图
│   ├── lobster_waiting_*.png
│   ├── lobster_working_*.png
│   ├── lobster_eating_*.png
│   ├── lobster_coding_done.png
│   ├── lobster_coding_error_1_1.png
│   └── lobster_sleepy_bubbles_*.png
└── plugin-hook/        # OpenClaw Plugin Hook（自动状态推送）
    ├── openclaw.plugin.json   # 插件清单
    ├── package.json           # 包配置
    └── index.js               # Hook 核心逻辑

---

❓ 常见问题

Electron 二进制未完整下载。删除后重新安装：

cd ~/.openclaw/skills/openclaw-companion
rm -rf node_modules/electron
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npm install electron

网络问题导致依赖下载超时。切换到国内镜像：

npm install --registry=https://registry.npmmirror.com

服务器环境通常没有 GPU 加速，这是预期行为，不影响龙虾功能。可忽略。

龙虾是一个桌面 GUI 应用，需要显示服务。以下方案可选：

• X11 Forwarding：ssh -X user@server，启动后窗口会转发到本地
• Xvfb 虚拟帧缓冲：xvfb-run npx electron . --no-sandbox
• VNC / 远程桌面：安装 VNC 服务后在远程桌面中启动

确保插件已正确安装到 ~/.openclaw/extensions/openclaw-companion-hook/，并在 openclaw.json 中启用了 openclaw-companion-hook。安装步骤见上方 Plugin Hook 安装 章节。没有该插件时，龙虾仍可通过手动 API 调用正常工作。

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

---

📄 License

MIT © 2025 L-LesterYu

---