@dai_ming/plugin-deliverables

OpenClaw 交付物插件 — 让 AI Agent 将生成的文件（文章、HTML 页面、多文件游戏/网站、图片等）自动上传到 OSS，并在会话消息中回显可点击的预览/下载链接。

插件包含什么

| 文件 | 作用 | |------|------| | index.js | Native OpenClaw runtime 入口：注册 before_prompt_build、before_tool_call、message_sending 三个 hook，阻止旁路文件发送 | | openclaw.plugin.json | Native OpenClaw 插件清单：让 OpenClaw 以 runtime plugin 方式发现并加载本插件 | | mcp-servers/deliverables.js | MCP Server 脚本：实现 upload_deliverable 工具，通过 HTTP 调用 claw-gateway API 上传文件 | | skills/deliverables/SKILL.md | OpenClaw Skill：强制文档产出走 upload_deliverable，规范写入路径和参数 | | agents-rules/deliverables.md | AGENTS.md 规则块：URL 回显规则 + 自动上传规则（硬约束，注入到每个 workspace 的 AGENTS.md） | | openclaw-plugin.json | claw-gateway 兼容清单：声明 MCP server、skill、AGENTS 规则、openclaw.json 配置段 |

安装方式

方式零：作为原生 OpenClaw runtime 插件安装

现在这个包同时支持 OpenClaw 原生插件加载。也就是说，除了网关侧用 openclaw-plugin.json 注入 MCP/skill/AGENTS 规则外，OpenClaw 还会读取 openclaw.plugin.json + index.js，把运行时 hook 也一并启用。

openclaw plugins install @dai_ming/[email protected] --pin
openclaw plugins enable plugin-deliverables

这一步启用后，插件会额外提供三层兜底：

1. before_prompt_build：把“交付物必须 upload-first”的硬规则注入到主 agent 和子 agent 的系统上下文
2. before_tool_call：记录 write 生成的工作区文件，并阻止通过 message 附件字段直接发文件
3. Palz 出站补丁：最终消息发送前扫描内部工作区路径/近期写入文件，自动上传为交付物并改写成 gateway 链接
4. message_sending：如果仍然有媒体/文件旁路发送，最终发送前直接取消

注意：非 Palz 渠道仍以 before_prompt_build + before_tool_call + message_sending 兜底为主；Palz 渠道具备自动上传和文本改写能力。

方式一：通过 claw-gateway Helm 部署（推荐）

只需在 Helm values 里把插件加入 installPlugins 列表，gateway 和 Helm initContainer 会自动完成所有配置：

# values.yaml（或 claw-gateway 管理界面的 Helm 参数）
installPlugins:
  - "@dai_ming/[email protected]"

initContainer 执行顺序：

1. Phase 3：npm pack @dai_ming/[email protected] 下载 tarball → 解压到 /data/extensions-extra/plugin-deliverables/
2. Phase 3b：在插件目录执行 npm install --omit=dev（本插件无运行时依赖，此步骤跳过）
3. Phase 3e：读取 openclaw-plugin.json 清单，自动：
   • 复制 mcp-servers/deliverables.js → /data/mcp-servers/deliverables.js
   • 安装 skills/deliverables/SKILL.md → 所有 workspace 的 skills/deliverables/SKILL.md
   • 注入 agents-rules/deliverables.md 内容到所有 workspace 的 AGENTS.md（幂等，按 marker 替换）
4. OpenClaw runtime 加载：OpenClaw 发现 openclaw.plugin.json + index.js 后，会自动启用 runtime hooks

env 变量：MCP Server 需要以下变量（claw-gateway 在生成 mcp.servers 配置时会自动注入）：

| 变量 | 说明 | 默认值 | |------|------|--------| | CLAW_GATEWAY_URL | gateway 内部地址 | http://claw-gateway:8080 | | CLAW_GATEWAY_PUBLIC_URL | gateway 公网地址（用于生成预览链接） | 同上 | | CLAW_GATEWAY_API_KEY | API Key | api-key-1 |

方式二：手动安装（不使用 claw-gateway 自动部署）

适用于自行管理 OpenClaw 容器的场景。

Step 1 — 下载并解压插件

npm config set registry https://registry.npmmirror.com
mkdir -p ~/.openclaw/extensions-extra/plugin-deliverables
cd /tmp && npm pack @dai_ming/plugin-deliverables
tar xzf openclaw-plugin-deliverables-*.tgz -C ~/.openclaw/extensions-extra/plugin-deliverables --strip-components=1

Step 2 — 复制 MCP Server 脚本

mkdir -p ~/.openclaw/mcp-servers
cp ~/.openclaw/extensions-extra/plugin-deliverables/mcp-servers/deliverables.js \
   ~/.openclaw/mcp-servers/deliverables.js

Step 3 — 安装 Skill

WORKSPACE=~/.openclaw/workspace   # 替换为实际 workspace 路径
mkdir -p "$WORKSPACE/skills/deliverables"
cp ~/.openclaw/extensions-extra/plugin-deliverables/skills/deliverables/SKILL.md \
   "$WORKSPACE/skills/deliverables/SKILL.md"

Step 4 — 注入 AGENTS.md 规则

AGENTS="$WORKSPACE/AGENTS.md"
RULES=~/.openclaw/extensions-extra/plugin-deliverables/agents-rules/deliverables.md

if grep -q "DELIVERABLE_LINK_RULES_START" "$AGENTS" 2>/dev/null; then
  # 已有旧规则，用 Node.js 按 marker 替换
  node -e "
    var fs=require('fs');
    var a=fs.readFileSync('$AGENTS','utf8');
    var r=fs.readFileSync('$RULES','utf8').trim();
    var re=/<!--\s*DELIVERABLE_LINK_RULES_START\s*-->[\s\S]*?<!--\s*DELIVERABLE_AUTO_UPLOAD_RULES_END\s*-->/g;
    fs.writeFileSync('$AGENTS', re.test(a) ? a.replace(re,r) : a+'\n\n'+r+'\n');
  "
else
  # 首次注入
  printf '\n\n' >> "$AGENTS"
  cat "$RULES" >> "$AGENTS"
fi

Step 5 — 配置 openclaw.json

在 ~/.openclaw/openclaw.json 的 mcp.servers 下添加：

{
  "mcp": {
    "servers": {
      "deliverables": {
        "command": "node",
        "args": ["/home/node/.openclaw/mcp-servers/deliverables.js"],
        "env": {
          "CLAW_GATEWAY_URL": "http://<your-gateway-host>:8080",
          "CLAW_GATEWAY_PUBLIC_URL": "https://<public-domain>",
          "CLAW_GATEWAY_API_KEY": "<your-api-key>"
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "plugin-deliverables": { "enabled": true }
    }
  }
}

AGENTS.md 规则说明

插件向每个 workspace 的 AGENTS.md 注入两段硬约束规则：

| 规则段 | Marker | 作用 | |--------|--------|------| | URL 回显规则 | DELIVERABLE_LINK_RULES_START … DELIVERABLE_LINK_RULES_END | 强制 Agent 上传后在消息中输出可点击的 Markdown 链接 | | 自动上传规则 | DELIVERABLE_AUTO_UPLOAD_RULES_START … DELIVERABLE_AUTO_UPLOAD_RULES_END | 当用户要求生成文件时默认自动上传，写入 output/ 目录 |

规则使用 HTML 注释 Marker 包裹，initContainer 和 Guardian 进程每次同步时都会幂等替换，不会产生重复块。

Skill 说明

skills/deliverables/SKILL.md 是 OpenClaw Skill，被注入到 workspace 后由 Agent 在工具调用前读取。它规定：

• 始终使用会话中实际暴露的工具名（deliverables__upload_deliverable）
• 生成文件统一写入 output/ 子目录
• 多文件（游戏/网站）优先用 type=game + files[]，不要提前打 zip
• 上传成功后回复必须附带 Markdown 格式的预览/下载链接

MCP Server 说明

mcp-servers/deliverables.js 是一个符合 MCP 协议（2024-11-05） 的 Node.js stdio server，暴露单个工具：

upload_deliverable

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | resource_id | string | ✅ | 当前会话唯一 ID | | type | enum | ✅ | article / game / zip / image / video / ppt / link | | file_name | string | ✅ | 用户可见文件名（含扩展名）或目录名 | | group_id | string | — | 群聊 ID | | user_id | string | — | 用户 ID | | content_text | string | — | 文本内容（单文件场景） | | content_base64 | string | — | Base64 编码的二进制内容（单文件场景）；工具会清理空白并校验格式 | | file_path | string | — | 本地文件路径，推荐用于 PDF/PPT/图片/zip 等二进制文件，工具会读取并自动编码 | | files | array | — | 多文件列表（游戏/站点场景，优先使用），每项可传 content_text、content_base64 或 file_path |

返回值包含 preview_url、download_url、reply_markdown（可直接附在回复消息中）。

Runtime Hook 说明

index.js 会在 OpenClaw runtime 中注册三个 hook：

| Hook | 作用 | |------|------| | before_prompt_build | 把“生成文件必须走交付物上传”的硬规则注入系统上下文，覆盖主 agent 和子 agent | | before_tool_call | 记录 write 生成的工作区文件；阻止通过 message 工具的 media/path/filePath/buffer 等字段直接发送文件 | | Palz 出站补丁 | 扫描最终消息中的 /data/workspace-*、output/*.ext、反引号文件名等工作区文件引用，自动上传后替换为交付物链接 | | message_sending | 如果上游仍然产生了媒体/文件旁路发送，在最终出站前直接取消 |

这些兜底一起工作的目标是：即使 prompt 漂移，也尽量把“工作区路径 / message + file/media”这类旁路堵住，统一收敛到 gateway 交付物链接。

另外，Palz 渠道下如果交付物回复包含可信 gateway 交付物链接，会被拆成“内容简介 + 最终链接”两条消息；任意外部 URL 或非 gateway OSS URL 不会被包装成 file_url 文件消息。runtime plugin 还会分别打印这两次真实 HTTP 发送的 request/response 日志，便于直接从 pod stdout 排查。

版本与发布

在 claw-gateway 仓库内发布

插件源码位于 packages/plugin-deliverables/ 目录，与 claw-gateway 主仓库同步维护。更新流程：

# 1. 修改 packages/plugin-deliverables/package.json 中的 version
# 2. 同步更新 packages/plugin-deliverables/mcp-servers/deliverables.js（如有变更）
# 3. 打包并发布到 npmmirror 兼容的私有或公开 registry
cd packages/plugin-deliverables
npm publish --registry https://registry.npmjs.org --access public

版本对齐建议

| claw-gateway 版本 | plugin 版本 | |-------------------|-------------| | 当前 | 1.0.22 |

常见问题

Q: 插件安装后 Agent 没有 upload_deliverable 工具怎么办？

检查以下几点：

1. openclaw.json 的 mcp.servers.deliverables 是否存在
2. MCP Server 是否在运行：kubectl exec <pod> -- ls /home/node/.openclaw/mcp-servers/
3. Agent 的 tools.allow 是否包含 deliverables__upload_deliverable

Q: 上传后没有返回链接怎么办？

确认 CLAW_GATEWAY_URL 和 CLAW_GATEWAY_API_KEY 注入正确，可在容器内测试：

curl -H "X-API-Key: $CLAW_GATEWAY_API_KEY" $CLAW_GATEWAY_URL/healthz

Q: claw-gateway 已经内置了 deliverables，会和插件冲突吗？

不会冲突。claw-gateway 通过 ConfigMap 注入的 MCP 脚本、skill、AGENTS 规则与插件内容完全一致。 Phase 3e（插件注入）在前，ConfigMap 阶段（Phase 4/4c/4d）在后；ConfigMap 的内容会覆盖插件安装的内容，两者互为备份。