89 lines
2.5 KiB
Markdown
89 lines
2.5 KiB
Markdown
# OpenClaw MCP 接入
|
||
|
||
## 功能
|
||
|
||
当前 MCP 提供四个工具：
|
||
|
||
- `yedir_get_current_user`：验证 Access Key 和作用域。
|
||
- `yedir_list_canvases`：列出当前用户的画布。
|
||
- `yedir_get_canvas`：读取画布节点、连线和 revision。
|
||
- `yedir_apply_canvas_operation`：执行带版本保护和幂等键的语义画布操作。
|
||
|
||
## 服务端准备
|
||
|
||
1. 执行数据库迁移：
|
||
|
||
```bash
|
||
pnpm db:migrate
|
||
```
|
||
|
||
2. 生产环境建议单独配置 `ACCESS_KEY_PEPPER`。未配置时使用 `AUTH_SECRET`。
|
||
|
||
3. 在视频画布的 Skills 入口创建 Access Key。Key 只显示一次，默认 90 天过期。
|
||
|
||
## 第三方按钉钉用户签发 Key
|
||
|
||
服务端配置一个不少于 32 字符的独立密钥：
|
||
|
||
```bash
|
||
MCP_KEY_PROVISIONING_SECRET="replace-with-a-random-service-secret"
|
||
```
|
||
|
||
受信第三方服务可以按钉钉用户名申请一个新的用户级 Key：
|
||
|
||
```bash
|
||
curl -X POST "https://your-yedir.example.com/api/openapi/v1/access-keys/provision" \
|
||
-H "Authorization: Bearer $MCP_KEY_PROVISIONING_SECRET" \
|
||
-H "Content-Type: application/json" \
|
||
--data '{
|
||
"dingTalkUsername": "张三",
|
||
"keyName": "OpenClaw 办公电脑",
|
||
"scopes": ["canvas:read", "canvas:write"],
|
||
"expiresInDays": 90
|
||
}'
|
||
```
|
||
|
||
返回的 `data.accessKey.token` 只显示一次。接口只匹配已启用且绑定过钉钉的用户；如果姓名重名，会返回 `DINGTALK_USERNAME_AMBIGUOUS`，此时必须同时提供 `dingTalkUserId`。第三方服务密钥只能保存在受信服务端，不得放入浏览器、移动端包或公开脚本。
|
||
|
||
## 安装本地 MCP
|
||
|
||
```bash
|
||
cd integrations/openclaw
|
||
npm install
|
||
```
|
||
|
||
验证 CLI：
|
||
|
||
```bash
|
||
YEDIR_BASE_URL="https://your-yedir.example.com" \
|
||
YEDIR_ACCESS_TOKEN="ydr_live_..." \
|
||
node ./cli.mjs me
|
||
```
|
||
|
||
添加到 OpenClaw：
|
||
|
||
```bash
|
||
openclaw mcp add yedir \
|
||
--command node \
|
||
--arg "/absolute/path/to/integrations/openclaw/mcp-server.mjs" \
|
||
--env "YEDIR_BASE_URL=https://your-yedir.example.com" \
|
||
--env "YEDIR_ACCESS_TOKEN=ydr_live_..."
|
||
|
||
openclaw mcp doctor yedir --probe
|
||
```
|
||
|
||
安装 Skill：
|
||
|
||
```bash
|
||
openclaw skills install \
|
||
/absolute/path/to/integrations/openclaw/yedir-canvas \
|
||
--as yedir-canvas
|
||
```
|
||
|
||
## 安全约束
|
||
|
||
- Access Key 仅保存 HMAC-SHA256 哈希，明文只在创建时返回。
|
||
- 当前支持 `canvas:read` 和 `canvas:write` 作用域。
|
||
- 移动、删除、替换媒体必须在用户明确确认后传入 `confirmed: true`。
|
||
- 画布页在没有本地编辑冲突时自动同步外部操作；发生冲突时不会用旧页面状态覆盖远端。
|