openclaw-onebot: Instructions file for Codex

OpenClaw OneBot 插件开发指南

项目概述

OpenClaw OneBot 是一个 OneBot v11 协议渠道插件，用于将 QQ（通过 Lagrange.Core/go-cqhttp/NapCat 等）接入 OpenClaw Gateway。

技术栈

• 语言: TypeScript
• 运行时: Node.js >= 22
• 构建工具: TypeScript Compiler (tsc)
• 包管理器: npm

核心依赖

{
  "dependencies": {
    "@clack/prompts": "^1.0.0",
    "cron": "^4.4.0",
    "fuse.js": "^7.1.0",
    "highlight.js": "^11.10.0",
    "marked": "^15.0.0",
    "tsx": "^4.0.0",
    "ws": "^8.17.0"
  },
  "optionalDependencies": {
    "satori": "^0.12.0",
    "sharp": "^0.33.0"
  }
}

项目结构

openclaw-onebot/
├── src/                    # 源代码
│   ├── index.ts           # 插件入口
│   ├── channel.ts         # OneBot 渠道实现
│   ├── connection.ts      # WebSocket 连接管理
│   ├── og-image.ts        # Markdown 转图片（satori）
│   ├── handlers/          # 消息处理器
│   │   └── process-inbound.ts
│   └── ...
├── dist/                  # 编译输出（.js）
├── test/                  # 测试脚本
│   └── render-og-image.ts
├── skills/                # OpenClaw 技能
├── themes/                # 主题文件
├── scripts/               # 工具脚本
├── package.json
├── tsconfig.json
└── openclaw.plugin.json   # 插件配置

开发工作流

1. 安装依赖

npm install

2. 开发模式

修改 TypeScript 源代码后需要重新编译：

npm run build

3. 测试图片生成功能

# 测试默认主题
npx tsx test/render-og-image.ts default

# 测试 dust 主题
npx tsx test/render-og-image.ts dust

# 输出位置
# test/output-render-default.png

4. 重启 OpenClaw 服务

# 停止服务
launchctl stop ai.openclaw.gateway

# 启动服务
launchctl start ai.openclaw.gateway

# 查看状态
openclaw status

5. 查看日志

# Gateway 日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# LaunchAgent 日志
tail -f /Users/kirigaya/.openclaw/logs/gateway.log

配置说明

OpenClaw 配置

配置文件位置: ~/.openclaw/openclaw.json

关键配置项：

{
  "channels": {
    "onebot": {
      "type": "forward-websocket",
      "host": "192.168.10.1",
      "port": 3001,
      "accessToken": "your-token",
      "enabled": true,
      "requireMention": true,        // 是否需要 @ 才响应
      "renderMarkdownToPlain": true,
      "longMessageMode": "og_image", // normal | og_image | forward
      "ogImageRenderTheme": "dust",  // 图片主题
      "longMessageThreshold": 300    // 超过此字符数转图片
    }
  },
  "plugins": {
    "load": {
      "paths": [
        "/Users/kirigaya/project/qqbot/openclaw-onebot"
      ]
    }
  }
}