ArkClaw Plugin

面向 OpenClaw 网关的 ArkClaw 扩展：在不修改 OpenClaw 核心的前提下，提供 Web 聊天历史分页能力与可选的消息重写。

功能特性

1. 错误文案重写（Hooks）

对已配置的错误文案进行统一重写（见下方 messageRewrite 配置）。

2. 历史会话索引（Session Key Index）

当会话被 /new 或 /reset 重置时，自动将旧 sessionId 写入持久化索引文件（.arkclaw-session-key-index.json），使后续 chat.history.paged 能够发现并合并所有同一 sessionKey 的历史 transcript。

3. Web 聊天网关方法

| 方法 | 说明 | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | chat.history.paged | 按 sessionKey 合并 store 内同一逻辑会话的多个 sessionId（含已 reset 的历史 ID）、当前与归档（.reset.* / .deleted.*）transcript，全局排序后基于 __openclaw.seq 游标分页返回。 |

chat.history.paged 请求参数（摘要）

| 字段 | 类型 | 说明 | | ------------ | -------- | ----------------------------------------------- | | sessionKey | string | 必填。 | | limit | number | 可选，默认 100，硬上限 1000。 | | before | number | 可选。若传入，只返回 seq < before 的较旧消息（上一页）；不传则返回最新一页。 |

响应中包含 messages、hasMore、oldestSeq、newestSeq，以及合并来源 sessionIdsMerged（若适用）。

性能说明（chat.history.paged）

当前实现会读入并解析相关 transcript 的全部 JSONL，合并排序后再截取一页。会话极长时 CPU、内存与延迟会上升。若成为瓶颈，需要在宿主侧引入按文件尾/索引增量等策略；详见源码 src/history/register.ts 顶部注释。

4. 依赖关系

• peer：openclaw >=2026.3.2（版本见 package.json 中 peerDependencies）。

源码结构

src/
  config.ts                    # 插件配置类型
  hooks.ts                     # 错误文案重写 hooks
  history/
    index.ts                   # barrel 导出
    register.ts                # registerWebchatHistory（hook + gateway method 注册）
    session-key-index.ts       # sessionKey → 历史 sessionId 持久化索引
    transcript.ts              # JSONL transcript 读取与路径发现
    sanitize.ts                # 消息清洗、信封剥离、截断、大小控制
    paginate.ts                # 跨文件排序与游标分页
  messaging/
    language.ts                # 语言检测
    rewrite.ts                 # 错误文案重写逻辑
  types/
    pi-coding-agent.d.ts       # 可选 peer 类型声明

安装

openclaw plugins install @arkclaw/arkclaw-plugin

配置

在 OpenClaw 配置文件 openclaw.json 中启用插件，例如：

{
  "plugins": {
    "entries": {
      "arkclaw-plugin": {
        "enabled": true,
        "config": {
          "messageRewrite": {
            "errorMessage": true
          }
        }
      }
    }
  }
}

配置字段

| 字段 | 类型 | 是否必填 | 说明 | | ----------------------------- | --------- | ---- | ---------------------- | | messageRewrite | object | 否 | 消息重写配置。 | | messageRewrite.errorMessage | boolean | 否 | 是否开启错误文案重写。默认 false。 |

（Web 网关方法无需额外 JSON 配置，安装并启用插件后即注册。）

客户端集成参考

仓库内 claw-client 示例：发送链路直接使用 OpenClaw 原生 chat.send；若检测到插件已安装，则历史列表优先调用 chat.history.paged 并通过 before 游标上拉加载；若未安装插件，则自动回退到原生 chat.history。

许可

Apache-2.0