第 11 章:高级场景:第三方平台集成
难度: ⭐⭐⭐ 进阶 预计阅读: 25 分钟 前置章节: 第 6 章、第 7 章
本章讲解 OpenClaw 与第三方平台的深度集成,包括 Google Workspace、Notion、GitHub、飞书等主流平台。通过 Skill 和 MCP 机制,Agent 可以直接操作外部服务,实现跨平台自动化。你将学习如何配置、测试并在生产环境中运用这些集成能力。
📑 本章目录
- 11.1 集成架构总览
- 11.2 Google Workspace 集成
- 11.3 GitHub 集成
- 11.4 飞书与 MCP 集成
- 11.5 集成调试与排障
- 实操练习
- 常见问题 (FAQ)
- 参考链接
- 本章小结
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:通过
gogSkill 统一操作 Gmail、Calendar、Drive 等服务。 - GitHub:通过
ghCLI 封装为 Skill,实现 Issue、PR、CI/CD 的自动化管理。 - 飞书与 MCP:内置消息通道 + MCP Server 深度集成,覆盖消息、文档、审批等场景。
- 调试排障:善用
openclaw doctor、日志查看和错误对照表快速定位问题。 - 最佳实践:遵循最小权限、凭证加密、速率限制等原则确保集成安全稳定。