OpenClaw Skills API网关（API Gateway）技能参考手册

概述

API Gateway（API网关）由Maton.ai提供，是一款支持托管OAuth授权的第三方API透传代理工具，可对接100+主流外部服务（如Google Workspace、Microsoft 365、GitHub、Notion、Slack、Airtable、HubSpot等）。当你需要与外部服务进行交互时，可直接使用该网关，无需单独处理每个服务的OAuth认证流程。

安全说明

MATON_API_KEY仅用于与Maton.ai的身份验证，本身不授予任何第三方服务的访问权限。每个外部服务都需要用户通过Maton的授权流程显式完成OAuth授权，且访问权限严格限定在用户已授权的连接范围内。

兼容性要求

• 网络可访问Maton.ai的网关服务
• 有效的Maton API密钥（MATON_API_KEY）

👤 作者：byungkyu
👉 Skills 下载地址：api-gateway-1.0.57.zip

快速开始

以下示例演示如何通过API Gateway调用Slack的原生API发送消息，代码包含详细中文注释：

## 导入所需模块：urllib.request（网络请求）、os（环境变量）、json（数据序列化/反序列化）
import urllib.request, os, json


## 构造Slack消息体：指定发送频道和消息内容
data = json.dumps({
    'channel': 'C0123456',  # 替换为你的Slack频道ID
    'text': 'Hello from gateway!'  # 要发送的消息内容
}).encode()  # 转换为字节流，适配HTTP请求格式


## 构造API Gateway请求：目标地址为Slack的chat.postMessage接口
req = urllib.request.Request(
    'https://gateway.maton.ai/slack/api/chat.postMessage',  # 网关地址+Slack应用标识+原生API路径
    data=data,  # 请求体
    method='POST'  # HTTP方法（与原生API一致）
)


## 添加认证头：使用MATON_API_KEY完成身份验证
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
## 指定请求体格式为JSON
req.add_header('Content-Type', 'application/json')


## 发送请求并解析响应
response = urllib.request.urlopen(req)
result = json.load(response)
## 格式化输出响应结果
print(json.dumps(result, indent=2))

运行步骤

1. 先配置环境变量：

   ## 替换为你的真实Maton API密钥
   export MATON_API_KEY="你的MATON_API_KEY"

2. 执行上述Python代码，即可向指定Slack频道发送消息。

核心概念

1. 基础URL格式

API Gateway的请求地址遵循固定格式，用于路由到对应第三方服务：

https://gateway.maton.ai/{app}/{native-api-path}

• {app}：服务标识（如slack、google-mail、notion，完整列表见「支持的服务」）
• {native-api-path}：第三方服务的原生API路径

关键注意事项：URL路径必须以服务标识开头。例如Gmail原生API路径为gmail/v1/users/me/messages，通过网关访问时需写为：

https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages

2. 身份认证

所有请求必须在请求头中携带Maton API密钥，格式如下：

Authorization: Bearer $MATON_API_KEY

配置API密钥（推荐方式）

将API密钥设置为环境变量，避免硬编码：

## 永久生效（需重启终端）：写入~/.bashrc或~/.zshrc
echo 'export MATON_API_KEY="你的API密钥"' >> ~/.bashrc
source ~/.bashrc


## 临时生效（当前终端会话）
export MATON_API_KEY="你的API密钥"

获取API密钥

1. 访问Maton.ai注册/登录账号
2. 进入Maton设置页面
3. 复制「API Key」区域的密钥即可

连接管理

连接管理用于创建、查询、删除第三方服务的OAuth连接，使用独立的基础地址：https://ctrl.maton.ai

1. 列出连接

查询指定服务的活跃连接，代码带中文注释：

import urllib.request, os, json


## 构造查询请求：筛选Slack的ACTIVE状态连接
req = urllib.request.Request(
    'https://ctrl.maton.ai/connections?app=slack&status=ACTIVE'
)
## 添加认证头
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')


## 发送请求并解析响应
response = urllib.request.urlopen(req)
connections = json.load(response)
## 格式化输出连接列表
print(json.dumps(connections, indent=2))

查询参数（可选）

• app：按服务名称筛选（如slack、hubspot、salesforce）
• status：按连接状态筛选（ACTIVE/活跃、PENDING/待授权、FAILED/失败）

响应示例

{
  "connections": [
    {
      "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
      "status": "ACTIVE",
      "creation_time": "2025-12-08T07:20:53.488460Z",
      "last_updated_time": "2026-01-31T20:03:32.593153Z",
      "url": "https://connect.maton.ai/?session_token=5e9...",
      "app": "slack",
      "method": "OAUTH2",
      "metadata": {}
    }
  ]
}

2. 创建连接

创建指定服务的OAuth连接，完成授权后即可使用：

import urllib.request, os, json


## 构造创建连接的请求体：指定要连接的服务
data = json.dumps({
    'app': 'slack'  # 要创建连接的服务标识
}).encode()


## 构造POST请求
req = urllib.request.Request(
    'https://ctrl.maton.ai/connections',
    data=data,
    method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')


## 发送请求并获取响应
response = urllib.request.urlopen(req)
result = json.load(response)
print(json.dumps(result, indent=2))

请求体参数

• app（必填）：服务名称（如slack、notion）
• method（可选）：连接方式（API_KEY/BASIC/OAUTH1/OAUTH2/MCP）

完成授权

创建连接后，响应中会返回一个url字段，在浏览器中打开该URL，按提示完成OAuth授权，授权成功后连接状态变为ACTIVE。

3. 获取单个连接详情

import urllib.request, os, json


## 替换为实际的连接ID
connection_id = "21fd90f9-5935-43cd-b6c8-bde9d915ca80"
req = urllib.request.Request(f'https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')


response = urllib.request.urlopen(req)
result = json.load(response)
print(json.dumps(result, indent=2))

4. 删除连接

import urllib.request, os, json


connection_id = "21fd90f9-5935-43cd-b6c8-bde9d915ca80"
## 构造DELETE请求
req = urllib.request.Request(
    f'https://ctrl.maton.ai/connections/{connection_id}',
    method='DELETE'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')


response = urllib.request.urlopen(req)
result = json.load(response)
print(json.dumps(result, indent=2))

5. 指定连接调用API

若同一服务有多个活跃连接，可通过Maton-Connection请求头指定使用的连接ID：

import urllib.request, os, json


data = json.dumps({
    'channel': 'C0123456',
    'text': 'Hello!'
}).encode()


req = urllib.request.Request(
    'https://gateway.maton.ai/slack/api/chat.postMessage',
    data=data,
    method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
## 指定使用的连接ID
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')


response = urllib.request.urlopen(req)
result = json.load(response)
print(json.dumps(result, indent=2))

若省略该头，网关默认使用该服务下创建时间最早的活跃连接。

支持的服务（部分核心服务）

完整服务列表可访问：https://clawhub.ai/byungkyu/api-gateway/services

常用场景示例

1. 调用Google Sheets获取表格数据

import urllib.request, os, json


## 构造请求：获取指定表格的A1:B2区域数据
req = urllib.request.Request(
    # 替换为你的表格ID和数据范围
    'https://gateway.maton.ai/google-sheets/v4/spreadsheets/122BS1sFN2RKL8AOUQjkLdubzOwgqzPT64KfZ2rvYI4M/values/Sheet1!A1:B2'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')


## 发送请求并解析结果
response = urllib.request.urlopen(req)
result = json.load(response)
print(json.dumps(result, indent=2))

2. 调用HubSpot创建联系人

import urllib.request, os, json


## 构造联系人数据
data = json.dumps({
    'properties': {
        'email': 'john@example.com',  # 联系人邮箱
        'firstname': 'John',  # 名
        'lastname': 'Doe'  # 姓
    }
}).encode()


## 构造创建联系人的请求
req = urllib.request.Request(
    'https://gateway.maton.ai/hubspot/crm/v3/objects/contacts',
    data=data,
    method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')


response = urllib.request.urlopen(req)
result = json.load(response)
print(json.dumps(result, indent=2))

3. Node.js版本调用Slack发送消息

// 异步函数：发送Slack消息
async function sendSlackMessage() {
  const response = await fetch('https://gateway.maton.ai/slack/api/chat.postMessage', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      // 从环境变量获取API密钥
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    },
    // 消息体：指定频道和内容
    body: JSON.stringify({ 
      channel: 'C0123456', 
      text: 'Hello! 来自API Gateway的消息' 
    })
  });
  // 解析响应并输出
  const result = await response.json();
  console.log(result);
}


// 执行函数
sendSlackMessage();

错误处理与故障排除

常见错误码说明

故障排查步骤

1. API密钥问题

## 检查环境变量是否配置
echo $MATON_API_KEY


## 验证密钥有效性
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

2. 服务标识错误

确认URL路径以正确的服务标识开头：

• 正确：https://gateway.maton.ai/google-mail/gmail/v1/users/me/messages
• 错误：https://gateway.maton.ai/gmail/v1/users/me/messages

3. 连接状态异常

## 检查指定服务的活跃连接
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-mail&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

速率限制

• 网关层面：每个账号每秒最多10次请求
• 第三方服务层面：遵循对应服务的原生API速率限制（如Slack、GitHub的限流规则）

注意事项与技巧

1. 参考原生API文档：各服务的端点路径、参数、请求方法均与原生API一致，可直接参考官方文档。
2. 请求头透传：除Host和Authorization外，自定义请求头会透传给第三方API。
3. 查询参数生效：URL中的查询参数会完整透传给第三方API。
4. HTTP方法支持：GET/POST/PUT/PATCH/DELETE均支持。
5. QuickBooks特殊处理：路径中使用:realmId会自动替换为已连接的realm ID。
6. curl使用技巧：URL包含[]（如fields[]）时，需加-g参数禁用glob解析：

   curl -g https://gateway.maton.ai/airtable/v0/...?fields[]=name&fields[]=email

附录

• 项目仓库：https://github.com/maton-ai/api-gateway-skill
• API参考文档：https://www.maton.ai/docs/api-reference
• 社区支持：https://discord.com/invite/dBfFAcefs2
• 技术支持：support@maton.ai