OpenClaw 接入百度App 配置指南

本指南帮助你配置百度App渠道，并接入 OpenClaw。

功能概览

| 功能 | 状态 | | :----------------------- | :--: | | 文本消息 | ✅ | | 主动发送消息 | ✅ | | 私聊 | ✅ | | Webhook 回调 | ✅ | | 入站文件下载与本地注入 | ✅ | | 出站本地文件上传后发送 | ✅ |

百度 App 渠道当前使用 V2 协议：鉴权只依赖 appKey / appSecret，消息体统一使用 msg.list 列表格式，文件上传 STS 路径为 /channel/file/sts。

当前实现行为

入站消息

• 回调路由使用 V2 路径：/channel/msg/callback；轮询模式对应 /channel/msg/poll。
• 入站 payload 使用 {sessionId, msg} 结构，其中 msg 为 {list:[{type,data}]}。
• 纯文本与文件消息都会按 msg.list 逐项解析进入 Agent。
• 插件会下载可访问的入站文件到本机临时目录 openclaw-baiduapp/media，并把成功下载的本地路径注入给 Agent。
• Agent 侧正文会保留原始文本，并在 [local files] 前追加 [files] 摘要行；其中 [local files] 只列出成功下载到本地的文件路径。单文件场景还会补充文件名和大小，下载失败时会追加明确的 failure placeholder，但不会伪造本地路径。

出站消息

• 出站消息同样使用 V2 的 msg.list 格式发送。
• 文件出站要求传入本地文件路径（如 /tmp/report.pdf 或 file:///tmp/report.pdf）。
• 插件会先基于 appKey / appSecret 生成 Bearer Token，再向 POST {apiBase}/channel/file/sts?ak={account.appKey}&token={generatedToken} 申请 SKS 凭证，上传到固定 BOS 端点 https://aisearch.bj.bcebos.com 后，再以 msg.list 格式发送给百度。
• fileType 优先使用显式 MIME；未指定时按本地文件扩展名推断，未知类型回退 application/octet-stream。

临时文件与清理

• 入站文件保留期固定为 7 天。
• 清理逻辑只遍历插件自有目录 openclaw-baiduapp/media，不会扫描或删除其他 tmp 路径内容。
• 清理在两个惰性时机触发：插件启动注册 webhook 后、以及每次入站文件处理结束后；失败只记录日志，不阻断主流程。

已知限制

• 出站文件发送只接受本地文件路径；远程 URL 不会被当作可发送附件直接透传。
• 发送消息接口使用 V2 JSON 协议，当前没有 multipart/form-data 消息发送实现。
• 只有成功下载到本地的入站文件才会出现在 Agent 的 [local files] 文本块与 MediaPath/MediaPaths 上下文里；下载失败的附件会在 agent 正文里留下 failure placeholder，但不会伪造本地路径。
• 本地 mock smoke 中，出站文件 happy/failure 闭环通过 scripts/mock-server.ts 的 /simulate-file-flow helper 验证，真实运行时代码本身由单元测试覆盖。

前置条件

1. 百度App 开发者账号
2. 公网可访问的 HTTPS 服务器（用于接收回调）
3. OpenClaw 已安装并运行

步骤一：安装插件

openclaw plugins install @searchfe/openclaw-baiduapp

步骤二：获取百度平台凭证

在百度App 开发者平台注册应用后，获取以下信息：

• App Key：应用标识
• App Secret：应用密钥

步骤三：配置 OpenClaw

使用命令行配置

openclaw config set channels.openclaw-baiduapp.appKey your-app-key
openclaw config set channels.openclaw-baiduapp.appSecret your-app-secret

或直接编辑配置文件

编辑 ~/.openclaw/openclaw.json：

{
    "channels": {
        "openclaw-baiduapp": {
            "appKey": "your-app-key",
            "appSecret": "your-app-secret"
        }
    }
}

配置说明

| 字段 | 必填 | 说明 | | :------------ | :--: | :----------------------------------- | | enabled | ✅ | 是否启用该渠道 | | webhookPath | ✅ | 回调路径，需与百度平台配置一致 | | appKey | ✅ | 应用 App Key（回调鉴权与主动发送必需） | | appSecret | ✅ | 应用 App Secret（回调鉴权与主动发送必需） |

环境变量支持

默认账户的凭证也可以通过环境变量设置：

| 环境变量 | 对应配置 | | :------------------ | :--------- | | BAIDU_APP_KEY | appKey | | BAIDU_APP_SECRET | appSecret |

步骤四：重启 Gateway

openclaw gateway restart

步骤五：验证配置

1. 在百度平台配置 Webhook 回调地址，指向你的 OpenClaw Gateway
2. 平台验证通过后，先发送一条测试文本消息，再发送一条带附件的 V2 msg.list 消息
3. 查看 OpenClaw 日志，确认 webhook 接收生效；如果是文件消息，还要确认插件完成本地下载并把 [local files] / MediaPaths 注入给 Agent

常见问题

Q: 保存配置时提示验证失败？

1. 检查 OpenClaw 是否已启动并监听正确端口
2. 确认 webhookPath 与平台 URL 路径一致
3. 确认 appKey 和 appSecret 与平台配置完全一致
4. 确认服务器公网可访问

Q: 消息接收成功但发送失败？

1. 检查 appKey、appSecret 是否正确
2. 查看 OpenClaw 日志获取详细错误信息

开发验证

pnpm test

pnpm build

更多本地 smoke、文件传输验证和 mock 证据查看方式见 doc/testing.md。

发布前检查矩阵

| 检查项 | 命令 | 预期结果 | 证据 | | :-- | :-- | :-- | :-- | | 单元测试 | pnpm test | 全部通过 | Vitest exit code 0 | | 构建 | pnpm build | 构建成功 | build exit code 0 |