openclaw-image-upload

v1.0.0

Published

8 days ago

OpenClaw 图片上传插件：当用户有上传图片意图时，将图片 base64 上传到指定接口并返回图片地址

0High
0Medium
0Low

hrbully1

openclaw plugin image upload

OpenClaw 图片上传插件

当用户有上传图片的意图时，将图片以 base64 上传到指定接口并返回图片地址。鉴权使用与 correct-demo-web 一致的 URL 签名（AK/SK 从环境变量读取）。

功能说明

注册 Agent 工具 upload_image，由 AI 在识别到用户「想上传图片」时调用。
将用户提供的图片（base64）发送到你配置的上传接口，请求体为 { image_base64: "..." }，响应中取 data.image_url 作为图片地址返回给用户。
请求 URL 带鉴权参数（与 correct-demo-web 的 calculateAuthUrl 一致），AK/SK 优先从运行 OpenClaw 的环境变量中读取，也可在插件配置中覆盖。

环境要求

Node.js 18+
已安装 OpenClaw

安装

方式一：从本地路径安装

# 在插件目录构建
cd /path/to/openclaw-qqbot
npm install
npm run build

# 在 OpenClaw 中安装（使用你本地的插件路径）
openclaw plugins install /path/to/openclaw-qqbot

方式二：从 npm 安装（若已发布）

openclaw plugins install openclaw-image-upload

安装后需在 OpenClaw 配置中填写插件配置并设置环境变量（见下文）。

配置

1. 环境变量（必填）

在运行 OpenClaw 的进程所在环境中设置以下变量，用于鉴权签名：

| 变量名 | 说明 | |--------|------| | OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_ID | 访问密钥 ID | | OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_SECRET | 访问密钥 Secret |

测试环境（当上传接口 URL 不包含 openai.100tal.com 时可选）：

| 变量名 | 说明 | |--------|------| | OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_ID_TEST | 测试环境 AccessKeyId | | OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_SECRET_TEST | 测试环境 AccessKeySecret |

示例（bash）：

export OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_ID="your-access-key-id"
export OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_SECRET="your-access-key-secret"

2. 插件配置

在 OpenClaw 的配置文件中为插件 image-upload 填写配置，例如 ~/.openclaw/openclaw.json：

{
  "plugins": {
    "entries": {
      "image-upload": {
        "config": {
          "uploadApiUrl": "https://your-upload-api.com/upload"
        }
      }
    }
  }
}

| 配置项 | 必填 | 说明 | |--------|------|------| | uploadApiUrl | 是 | 图片上传接口的基础 URL（不含鉴权 query，插件会自动追加签名参数） | | accessKeyId | 否 | 若填写，则覆盖环境变量中的 AccessKeyId | | accessKeySecret | 否 | 若填写，则覆盖环境变量中的 AccessKeySecret |

使用方式

安装并启用插件，配置好 uploadApiUrl 和环境变量（及可选的插件内 AK/SK）。
用户在对话中发送图片并表达上传意图（例如：「帮我把这张图上传」「上传这张图片」）。
AI 会调用 upload_image 工具，传入图片 base64。
插件将请求发往你配置的接口，并把返回的图片地址回复给用户（例如：「图片已上传，地址：https://...」）。

无需额外命令，由模型根据用户意图自动决定是否调用上传工具。

上传接口约定

插件与 correct-demo-web 使用的上传接口保持一致。

请求
- 方法：POST
- URL：你在配置中填写的 uploadApiUrl，插件会在其后追加鉴权 query（access_key_id、timestamp、signature、signature_nonce 等）。
- Body：Content-Type: application/json，{ "image_base64": "<去掉 data URL 前缀的 base64 字符串>" }。
响应
- 插件从 JSON 响应中读取 data.image_url 作为图片地址；若不存在则报错。
鉴权
- 与 correct-demo-web 的 calculateAuthUrl / getHttpSignature 一致，使用 HMAC-SHA1 对参数签名，时间戳为东八区 YYYY-MM-DDTHH:mm:ss。

若你的接口请求/响应格式不同，需要自行修改插件内 src/upload.ts 与 src/signatureClient.ts 以适配。

常见问题

Q: 提示「请设置环境变量 OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_ID 和 OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_SECRET」
A: 在启动 OpenClaw 的同一环境中设置上述两个环境变量（例如在 systemd 的 Environment=、.env 或当前 shell 的 export），然后重启 OpenClaw。

Q: 提示「请先在插件配置中设置 uploadApiUrl」
A: 在 OpenClaw 配置的 plugins.entries["image-upload"].config.uploadApiUrl 中填写你的上传接口基础 URL。

Q: 上传失败（HTTP 4xx/5xx 或接口返回非 JSON）
A: 检查 uploadApiUrl 是否正确、服务是否可用；确认接口鉴权方式与 correct-demo-web 一致（同一套 AK/SK 与签名算法）；查看 OpenClaw 日志中 [image-upload] 的错误信息。

Q: 测试环境与正式环境 AK/SK 不同
A: 正式环境（URL 包含 openai.100tal.com）使用 OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_ID / OPENCLAW_IMAGE_UPLOAD_ACCESS_KEY_SECRET；其他 URL 会优先使用 *_TEST 环境变量，若未设置则回退到非 TEST 的 AK/SK。

开发

npm install
npm run build   # 编译到 dist/
npm run dev     # 监听源码变更并编译

发布到 npm

登录 npm（若未登录）：
```
npm login
```
按提示输入 npm 用户名、密码和邮箱。
满足发布权限（出现 403 时必做）
npm 要求发布包时使用以下任一方式：
- 开启账号两步验证（2FA）：登录 npmjs.com → Account → Enable 2FA，再在终端用 npm login 登录后执行 npm publish。
- 或使用具备发布权限的 Access Token：
  npmjs.com → Account → Access Tokens → Generate New Token，类型选 Granular Access Token，Permissions 里勾选 Packages: Read and write，若需免 2FA 发布则勾选 Bypass 2FA for publish。
  生成后在本机配置（替代密码登录）：
```
npm config set //registry.npmjs.org/:_authToken=你的Token
```
  之后在该目录执行 npm publish 即可。
发布：
```
npm run build
npm publish
```
prepublishOnly 会在 publish 前自动执行一次 npm run build。
若使用私有 registry（如公司内网 npm）：先执行 npm config set registry <你的 registry 地址>，再执行 npm publish；或临时指定：npm publish --registry <地址>。
若包名已被占用：可将 package.json 中 name 改为带 scope，例如 @你的用户名/openclaw-image-upload，然后执行：
```
npm publish --access public
```

License

MIT