第 11 章：高级场景：第三方平台集成

难度: ⭐⭐⭐ 进阶 | 预计阅读: 25 分钟 | 前置章节: 第 6 章、第 7 章

本章讲解 OpenClaw 与第三方平台的深度集成，包括 Google Workspace、Notion、GitHub、飞书等主流平台。通过 Skill 和 MCP 机制，Agent 可以直接操作外部服务，实现跨平台自动化。你将学习如何配置、测试并在生产环境中运用这些集成能力。

11.1 集成架构总览

OpenClaw 通过两种方式集成第三方平台：Skill 封装 和 MCP Server。理解二者的区别是选择合适集成方案的关键。

集成方式对比

方式	原理	适用场景	开发难度	通信方向	典型代表
Skill 封装	将 CLI 工具或 API 封装为 Skill	已有成熟 CLI 的服务	低	单向调用	GitHub CLI、gog
MCP Server	通过 MCP 协议连接外部服务	需要实时双向通信的场景	中	双向通信	飞书、Notion

架构示意

Agent
 ├── Skill: gog → Google Workspace API
 ├── Skill: github → GitHub CLI (gh)
 ├── MCP: notion-server → Notion API
 ├── MCP: feishu-server → 飞书 API
 └── 自定义 Skill → 任意 REST API

通用配置模式

所有集成都遵循相同的四步配置模式：

安装: 将 Skill 目录放入 ~/.openclaw/workspace/skills/
认证: 在 Skill 配置或环境变量中设置 API Key
权限: 在 SKILL.md 中声明所需的权限范围
测试: 通过 Agent 对话验证功能

可以使用以下命令快速检查当前已安装的集成：

# 列出所有已安装的 Skill
ls ~/.openclaw/workspace/skills/

# 查看 McPorter 中已配置的 MCP Server
cat ~/.openclaw/workspace/config/mcporter.json | python3 -m json.tool

11.2 Google Workspace 集成

通过 gog Skill 集成 Gmail、Calendar、Drive 等 Google 服务。该 Skill 封装了 Google API，提供统一的 CLI 接口。

安装与认证

# 1. 获取 Google OAuth 凭证
# 在 Google Cloud Console 创建 OAuth 2.0 客户端 ID
# 下载 credentials.json

# 2. 配置凭证
cp credentials.json ~/.openclaw/workspace/skills/gog/

# 3. 首次认证（浏览器授权）
gog auth login

# 4. 验证认证状态
gog auth status

Gmail 操作

gog gmail search "from:boss@company.com after:2026/03/01"  # 条件搜索
gog gmail send to@email.com "标题" "内容"                    # 发送邮件
gog gmail labels                                              # 列出标签
gog gmail read <message-id>                                   # 读取邮件

Calendar 操作

gog calendar events --days 7      # 查看未来 7 天日程
gog calendar create "开会" --at "2026-03-08 14:00"  # 创建事件
gog calendar delete <event-id>    # 删除事件

Drive 操作

gog drive search "keyword"        # 搜索文件
gog drive download <file-id>      # 下载文件
gog drive upload ./report.pdf     # 上传文件
gog docs export <doc-id> md       # 导出文档为 Markdown
gog sheets get <sheet-id> A1:D10  # 读取表格范围

Google 服务命令速查

服务	命令前缀	核心操作	示例
Gmail	`gog gmail`	search / send / read	`gog gmail search "label:inbox"`
Calendar	`gog calendar`	events / create / delete	`gog calendar events --days 7`
Drive	`gog drive`	search / upload / download	`gog drive upload ./file.pdf`
Docs	`gog docs`	export / list	`gog docs export <id> md`
Sheets	`gog sheets`	get / update	`gog sheets get <id> A1:D10`

实际应用示例

# 每天早上发送日程摘要到飞书
tasks:
  - name: daily-calendar-summary
    prompt: |
      1. 用 gog calendar events --days 1 获取今天的日程
      2. 整理成摘要格式
      3. 通过飞书通道发送

11.3 GitHub 集成

通过 github Skill 封装 GitHub CLI (gh)，可以在 Agent 中直接管理仓库、Issue、PR 和 CI/CD。

配置认证

# 方式一：通过 gh 登录（交互式）
gh auth login

# 方式二：使用 Token（适合服务器环境）
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# 验证认证状态
gh auth status

常用操作

# Issue 管理
gh issue list --repo owner/repo --state open
gh issue create --title "Bug: XXX" --body "描述..."
gh issue comment <number> --body "已修复"

# PR 管理
gh pr list --repo owner/repo
gh pr create --title "feat: xxx" --body "说明..."
gh pr review <number> --approve
gh pr merge <number> --squash

# CI/CD 状态
gh run list --repo owner/repo --limit 5
gh run view <run-id> --log

# API 调用（高级）
gh api repos/owner/repo/releases --jq '.[0].tag_name'
gh api graphql -f query='{ viewer { login } }'

GitHub 操作速查

对象	列出	创建	操作
Issue	`gh issue list`	`gh issue create`	`gh issue close <n>`
PR	`gh pr list`	`gh pr create`	`gh pr merge <n>`
Release	`gh release list`	`gh release create`	`gh release delete <tag>`
CI Run	`gh run list`	—	`gh run rerun <id>`

自动化场景

# 每日项目状态报告
tasks:
  - name: github-daily-report
    prompt: |
      1. 用 gh 查看 owner/repo 的 open issues 和 PRs
      2. 检查最近 CI 运行状态
      3. 生成日报发送到飞书

11.4 飞书与 MCP 集成

飞书集成

OpenClaw 原生支持飞书作为消息通道，同时也可以通过 MCP 进行更深度的集成。

消息通道（内置）

// openclaw.json 中的飞书通道配置
{
  "channels": {
    "feishu-default": {
      "type": "feishu",
      "credentials": "feishu-default"
    }
  }
}

使用内置通道发送消息：

openclaw message send --channel feishu --target "<chat_id>" --message "Hello from Agent"

MCP Server 集成（高级）

通过 McPorter 配置 MCP Server，可以获得更丰富的飞书 API 能力（如操作文档、日历、审批等）：

// config/mcporter.json
{
  "servers": {
    "feishu-bot": {
      "command": "npx",
      "args": ["feishu-mcp-server"],
      "env": {
        "FEISHU_APP_ID": "your-app-id",
        "FEISHU_APP_SECRET": "your-app-secret"
      }
    }
  }
}

自定义 MCP 集成

McPorter 可以接入任何支持 MCP 协议的服务：

// 添加自定义 MCP Server
{
  "servers": {
    "my-api": {
      "command": "python3",
      "args": ["my_mcp_server.py"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

MCP Server 管理命令

# 查看当前 McPorter 配置
cat ~/.openclaw/workspace/config/mcporter.json

# 验证 MCP Server 是否可用（通过 Agent 对话测试）
# 在 Agent 中输入：请列出你目前可用的 MCP 工具

# 查看 MCP Server 日志
tail -f ~/.openclaw/logs/*.log | grep mcp

集成最佳实践

建议	说明	操作示例
最小权限原则	API Key 只给必要的权限	只授权 `read` 而非 `admin`
凭证加密存储	使用 `credentials/` 目录管理	避免明文写入 SKILL.md
错误重试	网络请求应配置重试机制	在 Skill 脚本中添加 retry 逻辑
速率限制	遵守 API 调用频率限制	批量操作间加 `sleep`
日志记录	记录所有外部调用以便排查	使用 `openclaw logs` 查看

11.5 集成调试与排障

当第三方集成出现问题时，可按以下流程排查：

排查步骤

# 1. 检查 Skill 目录结构是否正确
ls -la ~/.openclaw/workspace/skills/<skill-name>/

# 2. 确认 SKILL.md 中的声明完整
cat ~/.openclaw/workspace/skills/<skill-name>/SKILL.md

# 3. 验证认证凭证是否有效
# 以 GitHub 为例
gh auth status

# 4. 查看 OpenClaw 日志中的错误信息
tail -50 ~/.openclaw/logs/config-audit.jsonl

# 5. 运行诊断工具
openclaw doctor

常见错误对照表

错误信息	可能原因	解决方法
`401 Unauthorized`	API Key 过期或无效	重新生成并配置凭证
`403 Forbidden`	权限不足	检查 API Key 的 scope 设置
`429 Too Many Requests`	超出 API 速率限制	降低调用频率，增加间隔
`Connection refused`	MCP Server 未启动	检查 mcporter.json 配置和依赖
`Command not found`	CLI 工具未安装	安装对应的 CLI（如 `gh`、`gog`）

实操练习

以下练习帮助你掌握第三方平台集成的核心流程。请按顺序完成。

练习 1：查看并验证现有集成

目标：了解当前环境中已配置的集成。

# 步骤 1：列出所有已安装的 Skill
ls ~/.openclaw/workspace/skills/

# 步骤 2：查看 McPorter 中的 MCP Server 配置
cat ~/.openclaw/workspace/config/mcporter.json

# 步骤 3：检查凭证目录中的已配置认证
ls ~/.openclaw/credentials/

# 步骤 4：运行诊断确认环境健康
openclaw doctor

练习 2：配置 GitHub 集成并执行操作

目标：从零开始配置 GitHub 集成，并通过 Agent 操作仓库。

# 步骤 1：确认 gh CLI 已安装
gh --version

# 步骤 2：设置认证（使用 Token 方式）
export GITHUB_TOKEN=ghp_your_token_here

# 步骤 3：验证认证状态
gh auth status

# 步骤 4：通过 Agent 执行 GitHub 操作
# 在 Agent 对话中输入：
#   "请用 gh 列出我的仓库中最近的 5 个 open issues"

# 步骤 5：验证结果
gh issue list --state open --limit 5

练习 3：添加自定义 MCP Server

目标：学习如何向 McPorter 添加一个新的 MCP Server 集成。

# 步骤 1：查看当前 mcporter.json
cat ~/.openclaw/workspace/config/mcporter.json

# 步骤 2：备份当前配置
cp ~/.openclaw/workspace/config/mcporter.json \
   ~/.openclaw/workspace/config/mcporter.json.bak

# 步骤 3：编辑 mcporter.json，添加新的 MCP Server
# 在 "servers" 中添加如下配置：
#   "my-custom-server": {
#     "command": "npx",
#     "args": ["my-mcp-package"],
#     "env": { "API_KEY": "your-key" }
#   }

# 步骤 4：通过 Agent 验证新服务是否可用
# 在 Agent 对话中输入：
#   "请列出你目前可用的 MCP 工具"

# 步骤 5：如果出错，查看日志排查
tail -20 ~/.openclaw/logs/config-audit.jsonl

练习 4：构建跨平台自动化任务

目标：将多个集成组合，创建一个跨平台自动化流程。

# 创建任务定义文件：cross-platform-task.yaml
tasks:
  - name: cross-platform-daily-report
    schedule: "0 9 * * *"
    prompt: |
      1. 用 gh issue list 获取 GitHub 仓库中的 open issues
      2. 用 gog calendar events --days 1 获取今天的日程
      3. 将以上信息整理为日报格式
      4. 通过飞书通道发送到指定群组

# 验证任务定义的语法正确性
cat cross-platform-task.yaml | python3 -c "import yaml,sys; yaml.safe_load(sys.stdin); print('OK')"

常见问题 (FAQ)

Q1：如何添加新的第三方集成？

A：有两种方式：

Skill 封装：开发自定义 Skill（封装 CLI 工具），将目录放入 ~/.openclaw/workspace/skills/，编写 SKILL.md 声明权限。
MCP Server：在 config/mcporter.json 中添加 MCP Server 配置。

详见第 3 章 Skills 插件体系和第 4 章 Skills 安装与管理实践。

Q2：MCP 和 Skill 该选哪个？

A：决策依据如下：

如果有成熟的 CLI 工具（如 gh、gog），优先用 Skill 封装，开发成本低。
如果需要实时双向通信或没有 CLI 工具，用 MCP Server。
如果两者都可以，优先选 Skill——更简单、更稳定。

Q3：集成过多会影响性能吗？

A：不会显著影响。Skill 只在调用时加载，MCP Server 按需启动。但建议：

活跃集成不超过 20 个
不使用的 MCP Server 及时从 mcporter.json 中移除
使用 openclaw doctor 定期检查健康状态

Q4：API Key 泄露了怎么办？

A：立即执行以下操作：

# 1. 在第三方平台上撤销泄露的 Key
# 2. 生成新的 Key 并更新配置
# 3. 检查是否有异常调用记录
# 4. 更新凭证文件
ls ~/.openclaw/credentials/

Q5：如何测试集成是否正常工作？

A：推荐按以下步骤验证：

# 1. 检查 CLI 工具可用性
which gh && gh auth status

# 2. 运行 OpenClaw 诊断
openclaw doctor

# 3. 在 Agent 对话中直接测试
# 例如："请用 gh 查看我的 GitHub 用户名"

参考链接

平台/工具	文档地址	说明
GitHub CLI	https://cli.github.com/manual/	`gh` 命令完整参考
Google Workspace API	https://developers.google.com/workspace	Google 各服务 API 文档
飞书开放平台	https://open.feishu.cn/document/	飞书 API 与机器人开发文档
MCP 协议规范	https://modelcontextprotocol.io/	Model Context Protocol 官方规范
Notion API	https://developers.notion.com/	Notion 集成开发文档
OpenClaw Skill 开发指南	参见本教程第 3 章、第 4 章	Skill 开发与管理最佳实践

本章小结

集成架构：OpenClaw 通过 Skill 封装和 MCP Server 两种方式集成第三方平台，各有适用场景。
Google Workspace：通过 gog Skill 统一操作 Gmail、Calendar、Drive 等服务。
GitHub：通过 gh CLI 封装为 Skill，实现 Issue、PR、CI/CD 的自动化管理。
飞书与 MCP：内置消息通道 + MCP Server 深度集成，覆盖消息、文档、审批等场景。
调试排障：善用 openclaw doctor、日志查看和错误对照表快速定位问题。
最佳实践：遵循最小权限、凭证加密、速率限制等原则确保集成安全稳定。

#第 11 章：高级场景：第三方平台集成

#11.1 集成架构总览

#集成方式对比

#架构示意

#通用配置模式

#11.2 Google Workspace 集成

#安装与认证

#Gmail 操作

#Calendar 操作

#Drive 操作

#Google 服务命令速查

#实际应用示例

#11.3 GitHub 集成

#配置认证

#常用操作

#GitHub 操作速查

#自动化场景

#11.4 飞书与 MCP 集成

#飞书集成

#消息通道（内置）

#MCP Server 集成（高级）

#自定义 MCP 集成

#MCP Server 管理命令

#集成最佳实践

#11.5 集成调试与排障

#排查步骤

#常见错误对照表

#实操练习

#练习 1：查看并验证现有集成

#练习 2：配置 GitHub 集成并执行操作

#练习 3：添加自定义 MCP Server

#练习 4：构建跨平台自动化任务

#常见问题 (FAQ)

#Q1：如何添加新的第三方集成？

#Q2：MCP 和 Skill 该选哪个？

#Q3：集成过多会影响性能吗？

#Q4：API Key 泄露了怎么办？

#Q5：如何测试集成是否正常工作？

#参考链接

#本章小结