24c - 自定义集成教程

# 1. 访问 Google Cloud Console
# https://console.cloud.google.com
 
# 2. 创建新项目（或选择已有项目）
# → APIs & Services → Library → 搜索并启用以下 API：
#   - Gmail API
#   - Google Calendar API
#   - Google Drive API
#   - Google Sheets API
#   - Google Docs API
#   - People API（联系人）
 
# 3. 配置 OAuth 同意屏幕
# → APIs & Services → OAuth consent screen
# → 选择 "External" → 填写应用名称
# → 添加 Scopes：
#   - https://www.googleapis.com/auth/gmail.modify
#   - https://www.googleapis.com/auth/calendar
#   - https://www.googleapis.com/auth/drive
#   - https://www.googleapis.com/auth/contacts.readonly
#   - https://www.googleapis.com/auth/spreadsheets
#   - https://www.googleapis.com/auth/documents
# → 点击 "Publish App"（获取永久 token，否则 7 天过期）
 
# 4. 创建 OAuth 客户端 ID
# → APIs & Services → Credentials → Create Credentials → OAuth client ID
# → Application type: Desktop app
# → 下载 JSON 文件（client_secret_xxx.json）

# macOS 安装
brew install steipete/tap/gogcli
 
# 验证安装
gog --version
 
# 导入 OAuth 凭证
gog auth credentials /path/to/client_secret_xxx.json
 
# 添加 Google 账号并授权所有服务
gog auth add your-email@gmail.com \
  --services gmail,calendar,drive,contacts,docs,sheets
 
# 浏览器会自动打开，完成 Google 授权流程
# 授权成功后验证
gog auth list
# 预期输出：your-email@gmail.com  gmail,calendar,drive,contacts,docs,sheets

# 安装官方 gog Skill
npx playbooks add skill openclaw/openclaw --skill gog
 
# 或手动创建 Skill 文件
mkdir -p ~/.openclaw/skills

<!-- ~/.openclaw/skills/gmail-assistant/SKILL.md -->
# Gmail Assistant
 
管理 Gmail 收件箱：搜索、阅读、回复和发送邮件。
 
## 前置条件
- gog CLI 已安装并授权（`gog auth list` 确认）
- 默认账号已设置（`GOG_DEFAULT_ACCOUNT=your@gmail.com`）
 
## 使用场景
- 用户说"检查邮件"或"有什么新邮件"
- 用户说"回复 xxx 的邮件"
- 用户说"发邮件给 xxx"
- 用户说"搜索关于 xxx 的邮件"
 
## 操作指南
 
### 搜索邮件
```bash
# 搜索最近 7 天的邮件
gog gmail search 'newer_than:7d' --max 10 --json
 
# 搜索特定发件人
gog gmail messages search "from:boss@company.com in:inbox" \
  --max 20 --json
 
# 搜索未读邮件
gog gmail search 'is:unread in:inbox' --max 10 --json

# 纯文本邮件
gog gmail send \
  --to recipient@example.com \
  --subject "会议纪要" \
  --body-file - <<'EOF'
你好，
 
以下是今天会议的要点：
- 第一项决议
- 第二项决议
 
此致
EOF
 
# HTML 格式邮件
gog gmail send \
  --to recipient@example.com \
  --subject "周报" \
  --body-html "<h2>本周总结</h2><ul><li>完成功能 A</li><li>修复 Bug B</li></ul>"

# 回复特定邮件（需要原始 messageId）
gog gmail send \
  --to sender@example.com \
  --subject "Re: 原始主题" \
  --body "收到，我会处理。" \
  --reply-to-message-id <原始messageId>

gog gmail drafts create \
  --to recipient@example.com \
  --subject "待审核邮件" \
  --body-file ./draft-content.txt

**方式 C：Plugin 模式（高级——实时邮件推送）**

当你需要实时收到新邮件通知（而非轮询），可以使用 Gmail Pub/Sub + Plugin 的方式：

```typescript
// plugins/gmail-realtime/src/index.ts
import type { PluginApi } from '@openclaw/types';
import { google } from 'googleapis';

export function register(api: PluginApi) {
  // 注册 Gmail 实时监听工具
  api.registerTool({
    name: 'gmail-watch',
    description: '启动 Gmail 实时监听，新邮件到达时通过 Pub/Sub 推送通知',
    parameters: {
      labelIds: {
        type: 'array',
        items: { type: 'string' },
        description: '要监听的标签 ID 列表，默认 ["INBOX"]',
        optional: true
      }
    },
    execute: async ({ labelIds = ['INBOX'] }) => {
      const auth = new google.auth.GoogleAuth({
        keyFile: process.env.GOOGLE_SERVICE_ACCOUNT_KEY,
        scopes: ['https://www.googleapis.com/auth/gmail.readonly']
      });
      const gmail = google.gmail({ version: 'v1', auth });

      const res = await gmail.users.watch({
        userId: 'me',
        requestBody: {
          topicName: process.env.GMAIL_PUBSUB_TOPIC,
          // 例如 'projects/my-project/topics/gmail-notifications'
          labelIds
        }
      });

      return {
        historyId: res.data.historyId,
        expiration: res.data.expiration,
        message: `Gmail 监听已启动，将在 ${new Date(
          Number(res.data.expiration)
        ).toISOString()} 过期`
      };
    }
  });

  // 注册 Webhook 处理 Pub/Sub 推送
  api.registerWebhook({
    path: '/webhook/gmail-pubsub',
    handler: async (req) => {
      const message = JSON.parse(
        Buffer.from(req.body.message.data, 'base64').toString()
      );
      const { emailAddress, historyId } = message;

      // 获取新邮件详情
      const auth = new google.auth.GoogleAuth({
        keyFile: process.env.GOOGLE_SERVICE_ACCOUNT_KEY,
        scopes: ['https://www.googleapis.com/auth/gmail.readonly']
      });
      const gmail = google.gmail({ version: 'v1', auth });

      const history = await gmail.users.history.list({
        userId: 'me',
        startHistoryId: historyId,
        historyTypes: ['messageAdded']
      });

      return {
        newMessages: history.data.history?.length || 0,
        emailAddress,
        summary: '新邮件已到达，请检查收件箱'
      };
    }
  });
}

# 1. 访问 https://notion.so/my-integrations
# 2. 点击 "New integration"
# 3. 填写名称（如 "OpenClaw Agent"）
# 4. 选择关联的 Workspace
# 5. 设置 Capabilities：
#    - Content Capabilities: Read content, Update content, Insert content
#    - Comment Capabilities: Read comments（可选）
#    - User Capabilities: Read user information（可选）
# 6. 复制 API Key（以 ntn_ 或 secret_ 开头）

# 创建配置目录
mkdir -p ~/.config/notion
 
# 安全存储 API Key
echo "ntn_your_api_key_here" > ~/.config/notion/api_key
chmod 600 ~/.config/notion/api_key
 
# 或设置环境变量（在 .env 或 openclaw.json 中）
export NOTION_API_KEY="ntn_your_api_key_here"

# 在 Notion 中，对每个需要 Agent 访问的页面/数据库：
# → 点击右上角 "..." → "Connect to" → 选择你的 Integration 名称
#
# ⚠️ 这一步容易遗忘！Integration 只能访问显式授权的页面。
# 子页面会自动继承父页面的授权。

# 安装官方 Notion Skill
npx playbooks add skill openclaw/openclaw --skill notion

<!-- ~/.openclaw/skills/notion-pm/SKILL.md -->
# Notion 项目管理
 
通过 Notion API 管理项目任务、会议记录和知识库。
 
## 前置条件
- NOTION_API_KEY 已配置（`~/.config/notion/api_key` 或环境变量）
- 目标页面/数据库已授权给 Integration
 
## 使用场景
- 用户说"创建任务"或"添加待办"
- 用户说"查看项目进度"或"今天有什么任务"
- 用户说"记录会议纪要"
- 用户说"搜索知识库"
 
## API 配置
所有请求需要以下 Header：
```bash
NOTION_KEY=$(cat ~/.config/notion/api_key)
# 基础请求模板
curl -X [METHOD] "https://api.notion.com/v1/[endpoint]" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

curl -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "项目计划", "filter": {"property": "object", "value": "page"}}'

# 查询所有"进行中"的任务
curl -X POST "https://api.notion.com/v1/data_sources/[data_source_id]/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "Status",
      "select": {"equals": "进行中"}
    },
    "sorts": [{"property": "Priority", "direction": "ascending"}]
  }'

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "[你的数据库ID]"},
    "properties": {
      "Name": {"title": [{"text": {"content": "新任务标题"}}]},
      "Status": {"select": {"name": "待办"}},
      "Priority": {"select": {"name": "高"}},
      "Due Date": {"date": {"start": "2026-03-20"}},
      "Assignee": {"people": [{"id": "user_id"}]}
    }
  }'

curl -X PATCH "https://api.notion.com/v1/pages/[page_id]" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "已完成"}}}}'

curl -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "[会议记录父页面ID]"},
    "properties": {
      "title": {"title": [{"text": {"content": "2026-03-15 产品评审会议"}}]}
    },
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {"rich_text": [{"text": {"content": "参会人员"}}]}
      },
      {
        "object": "block",
        "type": "bulleted_list_item",
        "bulleted_list_item": {"rich_text": [{"text": {"content": "张三、李四、王五"}}]}
      },
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {"rich_text": [{"text": {"content": "决议事项"}}]}
      },
      {
        "object": "block",
        "type": "to_do",
        "to_do": {
          "rich_text": [{"text": {"content": "完成 v2.0 需求文档"}}],
          "checked": false
        }
      }
    ]
  }'

**Plugin 模式：Notion 双向同步**

当你需要 Notion 变更实时触发 Agent 行为时，可以使用 Plugin + Webhook 模式：

```typescript
// plugins/notion-sync/src/index.ts
import type { PluginApi } from '@openclaw/types';

const NOTION_API = 'https://api.notion.com/v1';
const NOTION_VERSION = '2025-09-03';

async function notionRequest(
  method: string,
  endpoint: string,
  body?: object
) {
  const apiKey = process.env.NOTION_API_KEY;
  const res = await fetch(`${NOTION_API}${endpoint}`, {
    method,
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Notion-Version': NOTION_VERSION,
      'Content-Type': 'application/json'
    },
    body: body ? JSON.stringify(body) : undefined
  });
  return res.json();
}

export function register(api: PluginApi) {
  // 批量创建任务工具
  api.registerTool({
    name: 'notion-batch-create',
    description: '批量创建 Notion 任务（从会议纪要或需求文档中提取）',
    parameters: {
      databaseId: { type: 'string', description: '目标数据库 ID' },
      tasks: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            title: { type: 'string' },
            status: { type: 'string', optional: true },
            priority: { type: 'string', optional: true },
            dueDate: { type: 'string', optional: true }
          }
        },
        description: '任务列表'
      }
    },
    execute: async ({ databaseId, tasks }) => {
      const results = [];
      for (const task of tasks) {
        const properties: Record<string, unknown> = {
          Name: { title: [{ text: { content: task.title } }] }
        };
        if (task.status) {
          properties.Status = { select: { name: task.status } };
        }
        if (task.priority) {
          properties.Priority = { select: { name: task.priority } };
        }
        if (task.dueDate) {
          properties['Due Date'] = { date: { start: task.dueDate } };
        }

        const result = await notionRequest('POST', '/pages', {
          parent: { database_id: databaseId },
          properties
        });
        results.push({
          id: result.id,
          title: task.title,
          url: result.url
        });

        // 遵守速率限制
        await new Promise(r => setTimeout(r, 350));
      }
      return { created: results.length, tasks: results };
    }
  });
}

# 1. 访问 https://github.com/settings/tokens?type=beta
# 2. 点击 "Generate new token"
# 3. 设置 Token 名称（如 "OpenClaw Agent"）
# 4. 设置过期时间（建议 90 天，定期轮换）
# 5. 选择 Repository access：
#    - "Only select repositories" → 选择需要的仓库
# 6. 设置 Permissions（最小权限原则）：
#    - Repository permissions:
#      - Contents: Read and write（克隆、推送）
#      - Issues: Read and write（创建/管理 Issue）
#      - Pull requests: Read and write（创建/审查 PR）
#      - Actions: Read-only（查看 CI 状态）
#      - Metadata: Read-only（必需）
# 7. 点击 "Generate token" 并复制

# 方式 A：使用 GitHub CLI 认证（推荐）
gh auth login --with-token <<< "ghp_your_token_here"
 
# 方式 B：存储到文件
mkdir -p ~/.config/github
echo "ghp_your_token_here" > ~/.config/github/pat
chmod 600 ~/.config/github/pat
 
# 方式 C：环境变量
export GITHUB_TOKEN="ghp_your_token_here"

# 安装官方 GitHub PAT Skill
npx playbooks add skill openclaw/skills --skill github-pat
 
# 验证 GitHub CLI 认证
gh auth status

<!-- ~/.openclaw/skills/github-devops/SKILL.md -->
# GitHub DevOps
 
管理 GitHub 仓库：PR 审查、Issue 管理、CI/CD 状态监控、代码搜索。
 
## 前置条件
- GitHub CLI（gh）已安装并认证（`gh auth status` 确认）
- 或 GITHUB_TOKEN 环境变量已设置
 
## 使用场景
- 用户说"检查 PR"或"有什么待审查的"
- 用户说"创建 Issue"或"报告 Bug"
- 用户说"CI 状态"或"部署情况"
- 用户说"搜索代码"或"找到 xxx 的实现"
 
## 操作指南
 
### PR 管理
```bash
# 列出待审查的 PR
gh pr list --repo owner/repo --state open --json number,title,author,reviewDecision
 
# 查看 PR 详情和 diff
gh pr view 42 --repo owner/repo
gh pr diff 42 --repo owner/repo
 
# 审查 PR（添加评论）
gh pr review 42 --repo owner/repo --comment --body "LGTM，但建议优化第 35 行的错误处理"
 
# 合并 PR
gh pr merge 42 --repo owner/repo --squash --delete-branch
 
# 创建 PR
gh pr create --repo owner/repo \
  --title "feat: 添加用户认证模块" \
  --body "## 变更说明\n- 实现 JWT 认证\n- 添加登录/注册 API\n\n## 测试\n- [x] 单元测试通过\n- [x] E2E 测试通过" \
  --base main --head feature/auth

# 列出 Issue
gh issue list --repo owner/repo --state open --label "bug" --json number,title,labels
 
# 创建 Issue
gh issue create --repo owner/repo \
  --title "Bug: 登录页面在 Safari 上白屏" \
  --body "## 复现步骤\n1. 打开 Safari\n2. 访问 /login\n3. 页面白屏\n\n## 预期行为\n显示登录表单\n\n## 环境\n- Safari 18.2\n- macOS 15.3" \
  --label "bug,priority:high"
 
# 关闭 Issue
gh issue close 15 --repo owner/repo --comment "已在 PR #42 中修复"

# 查看最近的 workflow 运行
gh run list --repo owner/repo --limit 5 --json databaseId,displayTitle,status,conclusion
 
# 查看特定运行的详情
gh run view 12345 --repo owner/repo
 
# 查看失败的日志
gh run view 12345 --repo owner/repo --log-failed
 
# 重新运行失败的 workflow
gh run rerun 12345 --repo owner/repo --failed

# 在仓库中搜索代码
gh search code "authentication middleware" --repo owner/repo --json path,textMatches
 
# 搜索文件
gh api "/search/code?q=filename:Dockerfile+repo:owner/repo" | jq '.items[].path'

# 查看最新 Release
gh release list --repo owner/repo --limit 3
 
# 创建 Release
gh release create v1.2.0 --repo owner/repo \
  --title "v1.2.0 - 用户认证" \
  --notes "## 新功能\n- JWT 认证\n- OAuth 2.0 支持\n\n## Bug 修复\n- 修复 Safari 白屏问题" \
  --latest

**Plugin 模式：GitHub Webhook 自动化**

当你需要 GitHub 事件（PR 创建、CI 失败、Issue 评论）自动触发 Agent 行为时：

```typescript
// plugins/github-automation/src/index.ts
import type { PluginApi } from '@openclaw/types';
import { createHmac } from 'crypto';

function verifyGitHubSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = 'sha256=' +
    createHmac('sha256', secret).update(payload).digest('hex');
  return signature === expected;
}

export function register(api: PluginApi) {
  // PR 审查助手工具
  api.registerTool({
    name: 'github-pr-analyze',
    description: '分析 GitHub PR 的变更，生成审查摘要',
    parameters: {
      owner: { type: 'string', description: '仓库所有者' },
      repo: { type: 'string', description: '仓库名称' },
      prNumber: { type: 'number', description: 'PR 编号' }
    },
    execute: async ({ owner, repo, prNumber }) => {
      const token = process.env.GITHUB_TOKEN;
      const headers = {
        'Authorization': `Bearer ${token}`,
        'Accept': 'application/vnd.github.v3+json',
        'User-Agent': 'OpenClaw-Agent'
      };

      // 获取 PR 信息
      const prRes = await fetch(
        `https://api.github.com/repos/${owner}/${repo}/pulls/${prNumber}`,
        { headers }
      );
      const pr = await prRes.json();

      // 获取变更文件列表
      const filesRes = await fetch(
        `https://api.github.com/repos/${owner}/${repo}/pulls/${prNumber}/files`,
        { headers }
      );
      const files = await filesRes.json();

      // 获取 CI 状态
      const checksRes = await fetch(
        `https://api.github.com/repos/${owner}/${repo}/commits/${pr.head.sha}/check-runs`,
        { headers }
      );
      const checks = await checksRes.json();

      return {
        title: pr.title,
        author: pr.user.login,
        state: pr.state,
        additions: pr.additions,
        deletions: pr.deletions,
        changedFiles: files.length,
        files: files.map((f: { filename: string; status: string; changes: number }) => ({
          path: f.filename,
          status: f.status,
          changes: f.changes
        })),
        ciStatus: checks.check_runs?.map(
          (c: { name: string; conclusion: string }) => ({
            name: c.name,
            conclusion: c.conclusion
          })
        ) || [],
        mergeable: pr.mergeable,
        reviewDecision: pr.review_decision
      };
    }
  });

  // GitHub Webhook 处理
  api.registerWebhook({
    path: '/webhook/github',
    handler: async (req) => {
      // 验证签名
      const signature = req.headers['x-hub-signature-256'];
      const secret = process.env.GITHUB_WEBHOOK_SECRET || '';
      if (!verifyGitHubSignature(
        JSON.stringify(req.body), signature, secret
      )) {
        return { error: 'Invalid signature', status: 401 };
      }

      const event = req.headers['x-github-event'];
      const payload = req.body;

      switch (event) {
        case 'pull_request':
          if (payload.action === 'opened' ||
              payload.action === 'synchronize') {
            return {
              action: 'analyze_pr',
              pr: {
                number: payload.pull_request.number,
                title: payload.pull_request.title,
                author: payload.pull_request.user.login,
                repo: payload.repository.full_name
              },
              message: `新 PR #${payload.pull_request.number}: ${payload.pull_request.title}`
            };
          }
          break;

        case 'workflow_run':
          if (payload.workflow_run.conclusion === 'failure') {
            return {
              action: 'ci_failure',
              workflow: payload.workflow_run.name,
              repo: payload.repository.full_name,
              branch: payload.workflow_run.head_branch,
              url: payload.workflow_run.html_url,
              message: `⚠️ CI 失败: ${payload.workflow_run.name} on ${payload.workflow_run.head_branch}`
            };
          }
          break;

        case 'issues':
          if (payload.action === 'opened') {
            return {
              action: 'new_issue',
              issue: {
                number: payload.issue.number,
                title: payload.issue.title,
                labels: payload.issue.labels.map(
                  (l: { name: string }) => l.name
                )
              },
              message: `新 Issue #${payload.issue.number}: ${payload.issue.title}`
            };
          }
          break;
      }

      return { action: 'ignored', event };
    }
  });
}

# 1. 访问 https://api.slack.com/apps
# 2. 点击 "Create New App" → "From scratch"
# 3. 填写 App 名称（如 "OpenClaw Agent"）
# 4. 选择目标 Workspace

# 在 Slack App 设置页面：
# → OAuth & Permissions → Scopes → Bot Token Scopes
# 添加以下最小权限集：
 
# 必需 Scopes：
# - chat:write          → 发送消息（核心功能）
# - channels:history    → 读取公共频道消息历史
# - groups:history      → 读取私有频道消息历史
# - im:history          → 读取私聊消息
# - mpim:history        → 读取群组私聊消息
# - users:read          → 解析 @mentions
# - app_mentions:read   → 检测 @bot 提及
 
# 可选 Scopes（按需添加）：
# - reactions:write     → 添加 emoji 反应
# - reactions:read      → 读取反应
# - pins:write          → 置顶消息
# - pins:read           → 读取置顶
# - files:write         → 上传文件
# - channels:read       → 列出频道

# 在 Slack App 设置页面：
# → OAuth & Permissions → Install to Workspace
# → 授权后复制 Bot User OAuth Token（以 xoxb- 开头）

// openclaw.json
{
  "channels": {
    "slack": {
      "enabled": true,
      "token": "${SLACK_BOT_TOKEN}",
      "appToken": "${SLACK_APP_TOKEN}",
      "channels": ["#general", "#engineering", "#alerts"],
      "allowedUsers": ["U01234ABCDE", "U05678FGHIJ"]
    }
  }
}

# 设置环境变量
export SLACK_BOT_TOKEN="xoxb-your-bot-token"
export SLACK_APP_TOKEN="xapp-your-app-token"  # Socket Mode 需要
 
# 启用 Socket Mode（推荐，无需公网 URL）：
# → Slack App 设置 → Socket Mode → Enable
# → 生成 App-Level Token（xapp- 开头）

# 安装官方 Slack Skill
npx playbooks add skill openclaw/openclaw --skill slack

<!-- ~/.openclaw/skills/slack-team/SKILL.md -->
# Slack 团队助手
 
通过 Slack 管理团队沟通：发送通知、管理频道消息、添加反应、置顶重要信息。
 
## 前置条件
- OpenClaw Slack 通道已配置并连接
- Bot 已被邀请到目标频道（在频道中 /invite @OpenClaw）
 
## 使用场景
- 用户说"发消息到 #engineering"
- 用户说"总结 #general 的讨论"
- 用户说"置顶这条消息"
- 用户说"给那条消息加个 ✅"
 
## 操作指南
 
### 发送消息
使用 OpenClaw 内置的 slack 工具：
- 发送到频道：`sendMessage` action，target 为 `channel:<channelId>`
- 发送私聊：`sendMessage` action，target 为 `user:<userId>`
- 回复线程：包含 `threadTs` 参数
 
### 读取消息历史
- 使用 `readMessages` action 获取频道最近消息
- 指定 `channelId` 和消息数量
- 用于在回复前了解上下文
 
### 添加反应
- 使用 `react` action
- 需要 `channelId`、`messageId`（Slack 时间戳格式如 1712023032.1234）
- 支持 Unicode emoji 或 `:name:` 格式
- 适合低噪音的确认（比发送文字回复更安静）
 
### 管理置顶
- `pinMessage`：置顶重要消息（决策、规范、周报）
- `unpinMessage`：取消置顶
- `listPins`：查看频道所有置顶消息
 
### 查询成员信息
- `memberInfo`：获取用户详情（名称、头像、状态）
- 用于在消息中正确 @mention 用户
 
## 消息格式注意事项
- Slack 使用 mrkdwn 格式（不是标准 Markdown）
- 粗体：`*text*`（不是 **text**）
- 斜体：`_text_`
- 代码：`` `code` `` 或 ```code block```
- 链接：`<https://url|显示文本>`
- @mention：`<@userId>`
- 频道引用：`<#channelId>`
- 消息长度限制：40,000 字符
 
## 安全规则
- 不要在公共频道发送包含密钥、密码的消息
- 批量发送消息时注意速率限制，避免刷屏
- 删除消息操作需要用户确认

// plugins/slack-automation/src/index.ts
import type { PluginApi } from '@openclaw/types';
 
export function register(api: PluginApi) {
  // Slack 频道摘要工具
  api.registerTool({
    name: 'slack-channel-digest',
    description: '生成 Slack 频道的消息摘要（最近 N 小时）',
    parameters: {
      channelId: { type: 'string', description: 'Slack 频道 ID' },
      hours: {
        type: 'number',
        description: '回溯小时数',
        optional: true
      }
    },
    execute: async ({ channelId, hours = 24 }) => {
      const token = process.env.SLACK_BOT_TOKEN;
      const oldest = Math.floor(
        (Date.now() - hours * 3600 * 1000) / 1000
      ).toString();
 
      // 获取消息历史
      const res = await fetch(
        'https://slack.com/api/conversations.history?' +
        new URLSearchParams({
          channel: channelId,
          oldest,
          limit: '200'
        }),
        {
          headers: { 'Authorization': `Bearer ${token}` }
        }
      );
      const data = await res.json();
 
      if (!data.ok) {
        return { error: data.error, hint: '确认 Bot 已被邀请到该频道' };
      }
 
      // 获取用户信息用于显示名称
      const userIds = [...new Set(
        data.messages.map((m: { user: string }) => m.user)
      )];
      const users: Record<string, string> = {};
      for (const uid of userIds) {
        const userRes = await fetch(
          `https://slack.com/api/users.info?user=${uid}`,
          { headers: { 'Authorization': `Bearer ${token}` } }
        );
        const userData = await userRes.json();
        if (userData.ok) {
          users[uid as string] =
            userData.user.real_name || userData.user.name;
        }
      }
 
      const messages = data.messages
        .reverse()
        .map((m: { user: string; text: string; ts: string }) => ({
          author: users[m.user] || m.user,
          text: m.text,
          time: new Date(parseFloat(m.ts) * 1000).toISOString()
        }));
 
      return {
        channel: channelId,
        period: `最近 ${hours} 小时`,
        messageCount: messages.length,
        messages,
        summary: `共 ${messages.length} 条消息，来自 ${Object.keys(users).length} 位成员`
      };
    }
  });
 
  // Slack 通知路由工具
  api.registerTool({
    name: 'slack-smart-notify',
    description: '根据紧急程度智能路由 Slack 通知',
    parameters: {
      message: { type: 'string', description: '通知内容' },
      severity: {
        type: 'string',
        description: '紧急程度',
        enum: ['info', 'warning', 'critical']
      },
      team: {
        type: 'string',
        description: '目标团队',
        enum: ['engineering', 'product', 'ops']
      }
    },
    execute: async ({ message, severity, team }) => {
      const token = process.env.SLACK_BOT_TOKEN;
 
      // 路由规则
      const routing: Record<string, Record<string, string>> = {
        engineering: {
          info: '#eng-general',
          warning: '#eng-alerts',
          critical: '#eng-incidents'
        },
        product: {
          info: '#product',
          warning: '#product-alerts',
          critical: '#product-urgent'
        },
        ops: {
          info: '#ops-log',
          warning: '#ops-alerts',
          critical: '#ops-incidents'
        }
      };
 
      const channel = routing[team]?.[severity] || '#general';
      const emoji = {
        info: 'ℹ️',
        warning: '⚠️',
        critical: '🚨'
      }[severity];
 
      const formattedMessage = `${emoji} *[${severity.toUpperCase()}]* ${message}`;
 
      const res = await fetch('https://slack.com/api/chat.postMessage', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          channel,
          text: formattedMessage,
          unfurl_links: false
        })
      });
      const data = await res.json();
 
      return {
        sent: data.ok,
        channel,
        severity,
        timestamp: data.ts
      };
    }
  });
}

需要用户级别的操作？
├── 是 → 用户数据敏感？
│   ├── 是 → OAuth 2.0（Gmail、Google Workspace）
│   └── 否 → PAT 或 API Key（GitHub、Notion）
└── 否 → 应用级别操作？
    ├── 是 → Bot Token（Slack、Discord）
    └── 否 → Service Account（服务间调用）

// 通用错误处理模板
async function safeApiCall<T>(
  name: string,
  fn: () => Promise<T>,
  retries = 3
): Promise<T | { error: string; retryable: boolean }> {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      return await fn();
    } catch (err: unknown) {
      const error = err as { status?: number; message?: string };
 
      // 速率限制 → 指数退避重试
      if (error.status === 429) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(
          `[${name}] 速率限制，${delay}ms 后重试（${attempt}/${retries}）`
        );
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
 
      // 认证失败 → 不重试
      if (error.status === 401 || error.status === 403) {
        return {
          error: `认证失败：${error.message}。请检查 API Key/Token 是否有效。`,
          retryable: false
        };
      }
 
      // 资源不存在 → 不重试
      if (error.status === 404) {
        return {
          error: `资源不存在：${error.message}。请检查 ID 是否正确。`,
          retryable: false
        };
      }
 
      // 服务器错误 → 重试
      if (error.status && error.status >= 500) {
        if (attempt === retries) {
          return {
            error: `服务暂时不可用（${error.status}），已重试 ${retries} 次。`,
            retryable: true
          };
        }
        await new Promise(r =>
          setTimeout(r, Math.pow(2, attempt) * 1000)
        );
        continue;
      }
 
      // 其他错误
      return {
        error: `未知错误：${error.message || String(err)}`,
        retryable: false
      };
    }
  }
  return { error: '重试次数耗尽', retryable: false };
}

# 客户反馈处理
 
## 每 30 分钟
- 搜索 Gmail 中标签为 "customer-feedback" 的未处理邮件
- 对每封反馈邮件：
  1. 分析邮件内容，判断类型（Bug / 功能请求 / 一般反馈）
  2. 在 Notion "客户反馈" 数据库中创建记录
  3. 如果是 Bug：在 GitHub 创建 Issue，标签为 "customer-reported"
  4. 在 Slack #product 频道发送摘要通知
  5. 给邮件添加 "processed" 标签
- 如果没有新反馈，回复 HEARTBEAT_OK

// openclaw.json
{
  "agents": {
    "list": [
      {
        "id": "feedback-bot",
        "agentDir": "~/.openclaw/agents/feedback",
        "model": "anthropic/claude-sonnet-4-5",
        "tools": {
          "profile": "coding",
          "allow": [
            "group:web",
            "group:fs",
            "slack",
            "notion-batch-create",
            "github-pr-analyze"
          ]
        },
        "heartbeat": {
          "every": "30m",
          "model": "anthropic/claude-haiku-4",
          "target": "slack",
          "to": "#product",
          "activeHours": { "start": "08:00", "end": "20:00" }
        }
      }
    ]
  }
}

# Identity
 
## Definition
我是客户反馈处理助手，负责从 Gmail 收集客户反馈，
分类后同步到 Notion 和 GitHub，并通知产品团队。
 
## Rules
 
| # | Rule |
|---|------|
| 1 | 每封反馈邮件只处理一次（检查 "processed" 标签） |
| 2 | Bug 报告必须同时创建 GitHub Issue |
| 3 | 所有反馈都记录到 Notion |
| 4 | 紧急 Bug（影响核心功能）立即通知，其他批量通知 |
| 5 | 不自动回复客户邮件，只做内部处理 |
 
## Decision Table
 
| 反馈类型 | Notion 状态 | GitHub | Slack 通知 |
|---------|------------|--------|-----------|
| Bug（紧急） | 🔴 紧急 | Issue + label:critical | 🚨 立即通知 |
| Bug（一般） | 🟡 待处理 | Issue + label:bug | 批量摘要 |
| 功能请求 | 🔵 评估中 | 不创建 | 批量摘要 |
| 一般反馈 | ⚪ 已记录 | 不创建 | 仅日报 |