---

name: api-gateway
description: |
通过托管式 OAuth 连接 100+ 个 API（Google Workspace、Microsoft 365、GitHub、Notion、Slack、Airtable、HubSpot 等）。
当用户需要与外部服务交互时使用此技能。
安全说明：MATON_API_KEY 仅用于 Maton.ai 身份验证，本身不授予第三方服务访问权限。每个服务都需要用户通过 Maton 的连接流程进行显式 OAuth 授权。访问权限严格限定于用户已授权的连接。由 Maton 提供 (https://maton.ai)。
compatibility: 需要网络访问权限和有效的 Maton API 密钥
metadata:
author: maton
version: "1.0"
clawdbot:
emoji: 🧠
homepage: "https://maton.ai"
requires:
env:
- MATON_API_KEY

API 网关

由 Maton 提供的直连第三方 API 的透传代理，采用托管式 OAuth 连接方案。该 API 网关支持直接调用原生 API 端点。

快速开始

# 原生 Slack API 调用示例  
python <<'EOF'  
import urllib.request, os, json  
data = json.dumps({'channel': 'C0123456', 'text': 'Hello from gateway!'}).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')  
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))  
EOF  

基础 URL

https://gateway.maton.ai/{应用名}/{原生API路径}  

将 {应用名} 替换为服务名称，{原生API路径} 替换为实际 API 端点路径。

重要提示：URL 路径必须以连接的应用名开头（例如 /google-mail/...）。此前缀用于告知网关使用哪个应用连接。例如原生 Gmail API 路径以 gmail/v1/ 开头，因此完整路径应类似 /google-mail/gmail/v1/users/me/messages。

认证

所有请求都需在 Authorization 头部包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

API 网关会自动为目标服务注入对应的 OAuth 令牌。

环境变量设置： 您可以将 API 密钥设为 MATON_API_KEY 环境变量：

export MATON_API_KEY="您的API密钥"

获取API密钥

1. 登录或注册 maton.ai 账号
2. 前往 maton.ai/settings
3. 点击 API Key 区域右侧的复制按钮获取密钥

连接管理

连接管理使用独立的基础 URL: https://ctrl.maton.ai

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=slack&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

查询参数（可选）:

• 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": {}
    }
  ]
}

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'slack'}).encode()
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')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

请求体:

• app (必填) - 服务名称（如 slack, notion）
• method (可选) - 连接方式 (API_KEY, BASIC, OAUTH1, OAUTH2, MCP)

获取连接

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

响应:

{
  "connection": {
    "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",
    "metadata": {}
  }
}

在浏览器中打开返回的 URL 以完成 OAuth 授权。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果同一应用存在多个连接，可通过添加 Maton-Connection 请求头指定要使用的连接 ID:

python <<'EOF'
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')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果未指定，网关将默认使用该应用最早建立的活跃连接。

支持的服务

示例

Slack - 发送消息 (原生API)

# Slack原生API: POST https://slack.com/api/chat.postMessage
python <<'EOF'
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; charset=utf-8')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

HubSpot - 创建联系人 (原生API)

# HubSpot原生API: POST https://api.hubapi.com/crm/v3/objects/contacts
python <<'EOF'
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')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Google Sheets - 获取表格数据 (原生API)

# Google Sheets原生API: GET https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{range}
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/122BS1sFN2RKL8AOUQjkLdubzOwgqzPT64KfZ2rvYI4M/values/Sheet1!A1:B2')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Salesforce - SOQL查询 (原生API)

# Salesforce原生API: GET https://{instance}.salesforce.com/services/data/v64.0/query?q=...
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/salesforce/services/data/v64.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Airtable - 列出表格 (原生API)

# Airtable原生API: GET https://api.airtable.com/v0/meta/bases/{id}/tables
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/airtable/v0/meta/bases/appgqan2NzWGP5sBK/tables')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Notion - 查询数据库 (原生API)

# Notion原生API: POST https://api.notion.com/v1/data_sources/{id}/query
python <<'EOF'
import urllib.request, os, json
data = json.dumps({}).encode()
req = urllib.request.Request('https://gateway.maton.ai/notion/v1/data_sources/23702dc5-9a3b-8001-9e1c-000b5af0a980/query', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Notion-Version', '2025-09-03')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Stripe - 列出客户 (原生API)

# Stripe原生API: GET https://api.stripe.com/v1/customers
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/stripe/v1/customers?limit=10')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

代码示例

JavaScript (Node.js)

const response = await fetch('https://gateway.maton.ai/slack/api/chat.postMessage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`
  },
  body: JSON.stringify({ channel: 'C0123456', text: 'Hello!' })
});

Python

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/slack/api/chat.postMessage',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={'channel': 'C0123456', 'text': 'Hello!'}
)

错误处理

来自目标 API 的错误会保留原始状态码和响应体直接透传。

故障排查：API 密钥问题

1. 检查是否已设置 MATON_API_KEY 环境变量：

echo $MATON_API_KEY

1. 通过列出连接验证 API 密钥有效性：

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

故障排查：无效应用名

1. 确认 URL 路径以正确的应用名开头。路径必须以 /google-mail/ 开头，例如：

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

1. 确保应用存在活跃连接。可通过以下命令验证：

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

故障排查：服务器错误

500 错误可能表示 OAuth 令牌已过期。请尝试通过上方「连接管理」创建新连接并完成 OAuth 授权。若新连接状态为"ACTIVE"，请删除旧连接以确保网关使用新配置。

速率限制

• 每个账户每秒 10 次请求
• 同时受目标 API 的速率限制约束

注意事项

• 当使用 curl 访问包含方括号的 URL 时（如 fields[]、sort[]、records[]），需添加 -g 参数来禁用通配符解析
• 当通过管道将 curl 输出传递给 jq 时，某些 shell 中环境变量可能无法正确展开，这会导致 "Invalid API key" 错误

使用技巧

1. 查阅原生 API 文档：各服务的 endpoint 路径和参数请参考其官方 API 文档

2. 请求头会透传：自定义头部（除 Host 和 Authorization 外）会被转发至目标 API

3. 查询参数有效：URL 中的查询参数会透传给目标 API

4. 支持所有 HTTP 方法：GET、POST、PUT、PATCH、DELETE 均可使用

5. QuickBooks 特殊处理：在路径中使用 :realmId 占位符，它会被自动替换为已连接的 realm ID

相关链接

• GitHub
• API 参考文档
• Maton 社区
• Maton 技术支持