OpenOffice Sync Plugin

OpenClaw plugin that syncs agent events to the OpenOffice gateway for real-time web visualization.

安装

1. 放置插件文件

将 .openclaw/extensions/openoffice-sync/ 目录放到你的项目根目录下：

your-project/
├── .openclaw/
│   └── extensions/
│       └── openoffice-sync/
│           ├── openclaw.plugin.json   # 插件配置 schema
│           ├── index.ts               # 插件运行时代码
│           └── README.md              # 本文件
├── src/
└── ...

2. 在 OpenClaw Gateway 配置中启用插件

编辑你的 OpenClaw gateway 配置文件（通常是 ~/.openclaw/config.json 或项目级配置）:

{
  "plugins": {
    "allow": ["openoffice-sync"],
    "entries": {
      "openoffice-sync": {
        "enabled": true,
        "config": {
          "gatewayUrl": "http://14.103.148.99:9199",
          "agentPrefix": "claw",
          "syncToolCalls": true,
          "syncMessages": true,
          "syncSubagents": true
        }
      }
    }
  }
}

注意: userId 留空即可，插件会自动从 $HOSTNAME → os.hostname() → 随机值 依次检测。

3. 确认 OpenOffice Gateway 服务正在运行

curl http://14.103.148.99:9199/health
# 期望输出: {"ok":true,"status":"live","mode":"http-polling"}

4. 启动 OpenClaw Gateway

正常启动即可，插件会自动注册并开始同步：

pnpm dev:gateway
# 或生产环境
node dist/index.js

查看同步日志

插件提供三种方式查看同步信息：

方式一：Web UI（推荐）

打开浏览器访问：

http://14.103.148.99:9199/pair?userId=claw-<你的hostname>

如果不知道你的 hostname，可以查看：

echo $HOSTNAME
# 或
hostname

Web UI 中可以看到：

• Agents 标签: Agent 卡片，实时状态指示（idle/working/done/error）
• Team 标签: 消息流（工具调用、聊天、状态更新）

方式二：JSONL 文件日志

插件会将每个同步事件写入 JSONL 文件（默认路径 ~/.openclaw/logs/openoffice-sync.jsonl）：

# 实时查看日志
tail -f ~/.openclaw/logs/openoffice-sync.jsonl

# 查看最近 20 条
tail -20 ~/.openclaw/logs/openoffice-sync.jsonl

# 只看失败的请求
grep '"ok":false' ~/.openclaw/logs/openoffice-sync.jsonl

# 格式化查看（需要 jq）
tail -5 ~/.openclaw/logs/openoffice-sync.jsonl | jq .

每行日志格式：

{
  "timestamp": "2026-03-31T10:00:00.123Z",
  "event": "inject",
  "eventType": "AGENT_STATUS",
  "agentId": "claw-main",
  "ok": true,
  "status": 202,
  "durationMs": 45
}

方式三：控制台输出

consoleMode 设置为 all（默认）时，所有同步事件会输出到 gateway 控制台：

[openoffice-sync] openoffice-sync: initialized — gateway=http://14.103.148.99:9199, userId=claw-myhost, ...
[openoffice-sync] openoffice-sync: connected to http://14.103.148.99:9199 as userId=claw-myhost
[openoffice-sync] inject AGENT_CREATED → 202 (32ms)
[openoffice-sync] inject AGENT_STATUS → 202 (18ms)
[openoffice-sync] inject TEAM_CHAT → 202 (25ms)

事件同步对照表

| OpenClaw Event | OpenOffice Action | Web UI Effect | |---|---|---| | Agent starts (before_model_resolve) | AGENT_CREATED + AGENT_STATUS → working | Agent card appears, status turns working | | Agent ends (agent_end) | AGENT_STATUS → done/error + TEAM_CHAT summary | Status updates, completion message in Team tab | | Tool call start (before_tool_call) | TEAM_CHAT (progress) | "[Tool] bash starting" in Team tab | | Tool call end (after_tool_call) | TEAM_CHAT (progress/review) | "[Tool] bash OK (1.2s)" in Team tab | | Message received (message_received) | TEAM_CHAT (chat) | User message shown in Team tab | | Message sent (message_sent) | TEAM_CHAT (chat) | Agent response shown in Team tab | | Subagent spawned (subagent_spawned) | AGENT_CREATED (working) | New agent card appears | | Subagent ended (subagent_ended) | AGENT_STATUS + AGENT_FIRED | Agent card removed | | Session start (session_start) | AGENT_STATUS → working | Main agent becomes active | | Session end (session_end) | AGENT_STATUS → idle | Main agent returns to idle | | Gateway start (gateway_start) | TEAM_CHAT (status) | "Gateway started" broadcast | | Gateway stop (gateway_stop) | All agents → idle | All agents go idle |

完整配置参考

{
  "plugins": {
    "allow": ["openoffice-sync"],
    "entries": {
      "openoffice-sync": {
        "enabled": true,
        "config": {
          "gatewayUrl": "http://14.103.148.99:9199",
          "userId": "",
          "agentPrefix": "claw",
          "syncToolCalls": true,
          "syncMessages": true,
          "syncSubagents": true,
          "messagePreviewChars": 200,
          "logFile": "~/.openclaw/logs/openoffice-sync.jsonl",
          "consoleMode": "all"
        }
      }
    }
  }
}

配置项说明

| Option | Default | Description | |---|---|---| | gatewayUrl | http://14.103.148.99:9199 | OpenOffice gateway HTTP URL | | userId | (auto-detect) | 用户 ID，留空自动从 $HOSTNAME / os.hostname() 生成 | | agentPrefix | claw | Agent ID 前缀 (如 claw-main, claw-sub-abc) | | syncToolCalls | true | 同步工具调用事件 | | syncMessages | true | 同步消息收发事件 | | syncSubagents | true | 同步子 agent 生命周期 | | messagePreviewChars | 200 | 消息预览最大字符数 | | logFile | ~/.openclaw/logs/openoffice-sync.jsonl | JSONL 日志文件路径（支持 ~） | | consoleMode | all | 控制台输出模式: off / errors-only / all |

多实例部署

运行多个 OpenClaw 实例时，使用不同的 userId 实现数据隔离：

• 实例 1: "userId": "openclaw-dev" → 访问 http://14.103.148.99:9199/pair?userId=openclaw-dev
• 实例 2: "userId": "openclaw-test" → 访问 http://14.103.148.99:9199/pair?userId=openclaw-test

架构

OpenClaw Agent
  ├─ before_model_resolve  ──→  POST /api/inject { AGENT_CREATED, AGENT_STATUS }
  ├─ after_tool_call       ──→  POST /api/inject { TEAM_CHAT }
  ├─ message_received      ──→  POST /api/inject { TEAM_CHAT }
  ├─ subagent_spawned      ──→  POST /api/inject { AGENT_CREATED }
  ├─ agent_end             ──→  POST /api/inject { AGENT_STATUS }
  └─ ...                        ↓
                           JSONL 日志文件 ← appendLog()
                                ↓
OpenOffice Web UI
  └─ GET /api/snapshot (每10秒轮询)  ←──  SQLite DB  ←──  /api/inject events

故障排查

| 问题 | 检查方式 | |---|---| | 插件未加载 | 检查 gateway 启动日志中是否有 [openoffice-sync] openoffice-sync: initialized | | 连接失败 | curl http://14.103.148.99:9199/health，确认 gateway 服务可达 | | 事件未显示 | 查看 JSONL 日志 grep '"ok":false'，检查是否有注入失败 | | Web UI 无数据 | 确认 URL 中的 userId 与插件配置/自动检测的 userId 一致 | | 日志文件不存在 | 检查 logFile 路径写权限，默认目录 ~/.openclaw/logs/ |