# OpenClaw 集成（由 Pica 提供支持） OpenClaw可以通过统一的集成层Pica与200多个第三方平台交互。 Pica 处理所有 OAuth、令牌刷新、速率限制和 API 规范化 - 您只需连接一次帐户，OpenClaw 就可以使用它们。 ## 设置用户需要满足两件事才能使用集成： 1. **Pica 帐户** — 在免费注册 2. **连接平台** — 在 Pica 仪表板中，连接您希望 OpenClaw 访问的服务（Gmail、Slack、HubSpot、Notion、Shopify 等）就是这样。一旦平台在 Pica 中连接，OpenClaw 就可以立即与其交互。无需管理 API 密钥，无需构建 OAuth 流程 — Pica 可以处理一切。 ## 链接 * **Pica 仪表板** — （管理连接和 API 密钥） * **Pica MCP 服务器** — （此技能在后台使用的 MCP 服务器） * **Pica 文档** — * **mcporter** — （将 OpenClaw 桥接到 Pica 的 MCP 客户端 CLI） ** ** ## 实施指南（针对在 OpenClaw 中设置 Pica 的开发人员） > **重要：** OpenClaw **不**支持 `openclaw.json` 中的本机 MCP 服务器配置。像“mcp”、“agents.defaults.mcp”或“mcp.servers”这样的密钥会被 OpenClaw 的配置验证器**拒绝**，并且会导致进程崩溃并出现“无法识别的密钥”错误。相反，Pica 集成通过 **skills + mcporter CLI** 进行工作 — 代理通过其 exec 工具将 mcporter 作为 shell 命令调用。 ### 架构开爪代理 └─ exec工具→shell命令 └─ mcporter 调用 pica.<工具> --args '...' --config <路径> └─ 生成 Pica MCP 服务器作为子进程 (stdio) └─ Pica API → Gmail、Slack、HubSpot 等 ### 所需文件 **1.`tools/package.json`** — mcporter + Pica MCP 依赖项 { "name": "异食癖桥", “版本”：“2.0.0”， “类型”：“模块”， “依赖项”：{ "mcporter": "^0.7.3", "@picahq/mcp": "^2.0.4" } } **2.`tools/mcporter.json`** — MCP 服务器注册表（mcporter 的配置） { “mcp服务器”：{ “异食癖”：{ “命令”：“节点”， “args”：[“/home/node/tools/node_modules/@picahq/mcp/build/index.js”]， “环境”：{ "PICA_SECRET": "$env:PICA_SECRET" } } } } > **重要：** 使用“node”作为已安装模块的绝对路径，而不是“npx”。使用“npx -y @picahq/mcp”会导致容器内冷启动下载缓慢。 `$env:PICA_SECRET` 语法是 mcporter 的环境变量替换 - 它在运行时从容器的环境中读取。 **3.`openclaw.json`** — 必须使用`skills.load.extraDirs`，而不是`mcp` { “代理”：{ “默认”：{ “工作空间”：“/home/节点/工作空间” } }, “技能”：{ “负载”：{ "extraDirs": ["/home/node/skills"] } } } **4\.此 SKILL.md** — 放置在技能目录中（例如 `/home/node/skills/openclaw-integrations/SKILL.md`） ### Dockerfile 设置 # 创建目录 RUN mkdir -p /home/node/tools /home/node/skills # 本地安装 mcporter + Pica MCP 复制工具/package.json /home/node/tools/ 运行 cd /home/node/tools && npm install # 麦克波特配置复制工具/mcporter.json /home/node/tools/config/mcporter.json # 将 mcporter 符号链接到 PATH，以便代理可以调用它运行 ln -s /home/node/tools/node_modules/.bin/mcporter /usr/local/bin/mcporter #复制技能复制技能/ /home/node/skills/ ### 环境变量变量|必填|描述 ---|---|--- `PICA_秘密` |是的 |来自的 API 密钥 `PICA_IDENTITY` |没有 |与用户/团队的范围连接（例如“user_123”） `PICA_IDENTITY_TYPE` |没有 |身份类型（例如“用户”） ### 常见陷阱 1. **请勿将`mcp`添加到`openclaw.json`** — OpenClaw 在任何级别都会拒绝它（`root.mcp`、`agents.defaults.mcp`）。该进程以代码 1 退出并且容器重新启动循环。 2. **请勿在 mcporter.json 中使用`npx`** — 它会在容器内的每次调用时下载包。使用带有预安装模块的绝对路径的“node”。 3. **请勿仅全局安装 mcporter** — Pica MCP 模块需要在本地安装，以便 mcporter 可以在已知的绝对路径中找到它。为了方便起见，将二进制文件符号链接到 PATH。 4. **Skills 目录必须在 OpenClaw 启动之前存在** — 如果 `extraDirs` 指向丢失的路径，OpenClaw 可能会默默地忽略它。 ** ** ## 你可以做什么连接平台的可能性示例： * **Gmail** — 阅读电子邮件、发送消息、管理草稿、组织标签 * **Slack** — 发布消息、阅读频道、管理用户 * **HubSpot** — 列出联系人、创建交易、管理公司 * **概念** — 创建页面、查询数据库、更新内容 * **Shopify** — 管理订单、产品、客户、库存 * **线性** — 创建问题、更新项目、跟踪进度 * **Google 日历** — 列出活动、创建会议、管理日程 * **GitHub** — 管理存储库、问题、拉取请求 * 以及 190 多个平台 ** ** ## 工作原理（针对代理）通过“mcporter”访问集成，这是一个连接到 Pica MCP 服务器的 MCP 客户端 CLI。 ### mcporter 命令格式 **重要**：始终使用“--args”和 JSON 字符串作为工具参数。不要使用冒号分隔的语法（`key:value`），因为像 `--json` 这样的全局标志会被误解为工具参数。每次调用的正确格式是： mcporter 调用 pica.<工具名称> --args '' --config /home/node/tools/config/mcporter.json ### 工具工具|目的 ---|--- `list_pica_integrations` |查看连接了哪些平台 `search_pica_platform_actions` |查找平台上可用的操作 `get_pica_action_knowledge` |使用操作之前请阅读相关文档 `execute_pica_action` |在连接的平台上运行操作 ** ** ### 第 1 步：检查已连接的内容 mcporter 调用 pica.list_pica_integrations --args '{}' --config /home/node/tools/config/mcporter.json **响应结构：** { “连接”：[ { "platform": "gmail", "key": "test::gmail::default::abc123" }, { "platform": "slack", "key": "test::slack::default::def456" } ], “可用”：[ { "platform": "notion", "name": "Notion", "category": "生产力" } ], “摘要”：{“已连接计数”：10，“可用计数”：205 } } * `connections[].key` 是 `connectionKey` — 您将在第 4 步中需要它 * `connections[].platform` 是步骤 2-4 的短横线平台名称 * `available` 列出了可以连接但尚未连接的平台 * 如果用户所需的平台位于“可用”（而不是“连接”）中，请告诉他们通过连接它 ### 第 2 步：找到正确的行动 mcporter 调用 pica.search_pica_platform_actions --args '{"platform":"gmail","query":"发送电子邮件"}' --config /home/node/tools/config/mcporter.json **参数：** * `platform`（必需）：步骤 1 中的短横线格式的平台名称 * `query`（必需）：你想要做什么的自然语言描述 * `agentType`（可选）：当用户想要执行操作时`"执行"`，当用户想要信息时`"知识"` **响应结构：** { “行动”：[ { "actionId": "conn_mod_def::GGXAjWkZO8U::uMc1LQIHTTKzeMm3rLL5gQ", "title": "发送邮件", “方法”：“发布”， “路径”：“/gmail/发送电子邮件” } ], “元数据”：{“平台”：“gmail”，“查询”：“发送电子邮件”，“计数”：5 } } * 步骤 3 和 4 需要 `actions[].actionId` * 最多返回 5 个结果，按相关性排名 * 对于 Gmail，优先选择以 `/gmail/` 开头的路径的操作（这些是具有更清晰请求/响应格式的“增强”操作），而不是像 `users/me/messages/...` 这样的原始 API 路径 ### 第 3 步：阅读操作文档 mcporter 调用 pica.get_pica_action_knowledge --args '{"actionId":"","platform":"gmail"}' --config /home/node/tools/config/mcporter.json **参数：** * `actionId`（必需）：来自步骤 2 * `platform` (必填): 短横线格式的平台名称 **您必须在执行之前调用此函数。** 响应包含必需参数、可选参数、请求正文架构、响应格式和重要注意事项。不要猜测参数 - 首先阅读文档。 ### 第 4 步：执行操作 mcporter 调用 pica.execute_pica_action --args '{"platform":"gmail","actionId":"conn_mod_def::GGXAjWkZO8U::uMc1LQIHTTKzeMm3rLL5gQ","connectionKey":"test::gmail::default::abc123","data":{"to":"user@example.com","subject":"你好","body":"你好"}}' --config /home/node/tools/config/mcporter.json **参数：** * `platform` (必填): 短横线格式的平台名称 * `actionId`（必需）：来自步骤 2 * `connectionKey`（必需）：来自步骤 1 (`connections[].key`) * `data` （可选）：请求主体对象 — 内容取决于操作（参见步骤 3） * `queryParams` (可选): 查询字符串参数对象 * `pathVariables`（可选）：URL 路径变量替换对象 * `headers` （可选）：附加 HTTP 标头对象 * `isFormData` （可选）：布尔值，对于 multipart/form-data 设置为 true * `isFormUrlEncoded`（可选）：布尔值，对于 URL 编码的表单数据设置 true **所有参数都位于`--args` JSON 字符串中**，包括作为嵌套对象的“data”。 ** ** ## 响应格式 **切勿将原始 JSON 或工具输出转储给用户。** 始终解析并呈现清晰的摘要。 * **列出集成** — 显示已连接平台名称的干净列表。不显示连接密钥或 ID。 * 好：“您已连接 **Gmail** 、 **Slack** 和 **HubSpot**。” * **搜索结果** — 仅包含操作标题的简短编号列表。 * 好：“我发现了这些 Gmail 操作：\n1. **发送电子邮件** \n2. **列出电子邮件** \n3. **创建草稿** ” * **操作文档** - 用简单的语言总结所需的参数。 * 好：“要发送电子邮件，我需要：收件人、主题和正文。我还可以添加抄送/密件抄送。” * **执行结果** — 一句话描述发生了什么。 * 好：“完成 — 电子邮件发送至 [alice@example.com]()。” * **错误** — 用通俗易懂的语言进行解释并提出修复建议。没有堆栈跟踪。 ## 指南 * 当用户第一次询问集成时，调用“list_pica_integrations”来显示可用的内容 * 如果被问到“你能用 X 做什么？”，搜索该平台上的操作并总结功能 * 对于 Gmail，与原始 API 操作相比，更喜欢增强操作（以“/gmail/”开头的路径）——它们具有更简单的参数并返回解码的、人类可读的数据 * 执行前务必与用户确认破坏性操作（删除、批量操作） * 切勿在响应中暴露连接密钥、API 机密或内部 ID * 如果出现问题，请清楚地解释并建议后续步骤（例如，“该平台尚未连接 - 您可以在添加它”）

龙虾集成

包含技能