# 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`。
- 画布页在没有本地编辑冲突时自动同步外部操作；发生冲突时不会用旧页面状态覆盖远端。