Salesforce：托管 OAuth CRM API 集成 - Openclaw Skills

什么是 Salesforce CRM 集成？

Salesforce 技能使开发人员和 AI 代理能够直接与 Salesforce REST API 交互，而无需繁琐的手动 OAuth 生命周期管理。通过利用 Openclaw Skills 框架，此集成提供了一个安全网关，可自动处理令牌注入和实例路由。它允许与核心 CRM 实体（包括客户、联系人、潜在客户和机会）进行深度交互。

此技能专为高性能 CRM 操作而设计，支持从简单的单条记录 CRUD 操作到复杂的批量处理和 SOQL 查询的一切。它充当您的本地开发环境与 Salesforce 云之间的桥梁，确保您的代理能够以极简的配置读取、写入和搜索客户数据。

下载入口:https://github.com/openclaw/skills/tree/main/skills/byungkyu/salesforce-api

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install salesforce-api

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 <project>/skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 salesforce-api。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Salesforce CRM 集成 应用场景

• 通过 AI 代理自动化线索获取和跟进序列。
• 运行复杂的 SOQL 查询以生成实时销售报告。
• 在外部数据库和 Salesforce sObject 之间同步数据。
• 通过创建和更新案例记录来管理支持工作流。
• 使用复合批量请求对机会阶段进行批量更新。

Salesforce CRM 集成 工作原理

1. 用户通过 Maton 控制面板创建到 Salesforce 的活动连接。
2. 请求使用标准 Salesforce REST API 路径结构发送到网关 URL。
3. 网关通过提供的 Maton API 密钥识别用户。
4. 它会自动注入正确的 OAuth 访问令牌，并将请求路由到特定的 Salesforce 实例。
5. Salesforce API 处理请求（SOQL、CRUD 或搜索）并通过网关将数据返回给用户。

Salesforce CRM 集成 配置指南

要使用 Openclaw Skills 将此技能集成到您的工作流程中，请按照以下安装步骤操作：

1. 将您的 Maton API 密钥设置为环境变量：

export MATON_API_KEY="YOUR_API_KEY"

2. 创建一个新的 Salesforce 连接以授权访问：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'salesforce'}).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

3. 导航到响应中返回的 URL 以完成 OAuth 流程。

Salesforce CRM 集成 数据架构与分类体系

该技能与标准 Salesforce sObject 交互并以 JSON 格式返回数据。以下是支持的主要对象：

对象	描述	关键字段
Account	业务实体	Name, Industry, Type
Contact	个人	FirstName, LastName, Email
Lead	潜在客户	Company, Status, Rating
Opportunity	销售交易	Amount, StageName, CloseDate
Case	支持问题	CaseNumber, Subject, Status
Task	待办事项	ActivityDate, Description, Priority

name: salesforce
description: |
  Salesforce CRM API integration with managed OAuth. Query records with SOQL, manage sObjects (Contacts, Accounts, Leads, Opportunities), and perform batch operations. Use this skill when users want to interact with Salesforce data. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: ??
    requires:
      env:
        - MATON_API_KEY

Salesforce

Access the Salesforce REST API with managed OAuth authentication. Query records using SOQL, manage sObjects, and perform CRUD operations on your Salesforce data.

Quick Start

# Query contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/salesforce/services/data/v59.0/query?q=SELECT+Id,Name,Email+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

Base URL

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

Replace {native-api-path} with the actual Salesforce REST API endpoint path. The gateway proxies requests to {instance}.salesforce.com (automatically replaced with your connection config) and injects your access token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Salesforce OAuth connections at https://ctrl.maton.ai.

List Connections

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

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'salesforce'}).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

Get Connection

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

Response:

{
  "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=...",
    "app": "salesforce",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

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

Specifying Connection

If you have multiple Salesforce connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/salesforce/services/data/v59.0/sobjects')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

SOQL Query

GET /salesforce/services/data/v59.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10

Complex query:

GET /salesforce/services/data/v59.0/query?q=SELECT+Id,Name,Email+FROM+Contact+WHERE+Email+LIKE+'%example.com'+ORDER+BY+CreatedDate+DESC

Get Object

GET /salesforce/services/data/v59.0/sobjects/{objectType}/{recordId}

Example:

GET /salesforce/services/data/v59.0/sobjects/Contact/003XXXXXXXXXXXXXXX

Create Object

POST /salesforce/services/data/v59.0/sobjects/{objectType}
Content-Type: application/json

{
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "[email protected]"
}

Update Object

PATCH /salesforce/services/data/v59.0/sobjects/{objectType}/{recordId}
Content-Type: application/json

{
  "Phone": "+1234567890"
}

Delete Object

DELETE /salesforce/services/data/v59.0/sobjects/{objectType}/{recordId}

Describe Object (get schema)

GET /salesforce/services/data/v59.0/sobjects/{objectType}/describe

List Objects

GET /salesforce/services/data/v59.0/sobjects

Search (SOSL)

GET /salesforce/services/data/v59.0/search?q=FIND+{searchTerm}+IN+ALL+FIELDS+RETURNING+Contact(Id,Name)

Composite Request (batch multiple operations)

POST /salesforce/services/data/v59.0/composite
Content-Type: application/json

{
  "compositeRequest": [
    {
      "method": "GET",
      "url": "/services/data/v59.0/sobjects/Contact/003XXXXXXX",
      "referenceId": "contact1"
    },
    {
      "method": "GET",
      "url": "/services/data/v59.0/sobjects/Account/001XXXXXXX",
      "referenceId": "account1"
    }
  ]
}

Composite Batch Request

POST /salesforce/services/data/v59.0/composite/batch
Content-Type: application/json

{
  "batchRequests": [
    {"method": "GET", "url": "v59.0/sobjects/Contact/003XXXXXXX"},
    {"method": "GET", "url": "v59.0/sobjects/Account/001XXXXXXX"}
  ]
}

sObject Collections Create (batch create)

POST /salesforce/services/data/v59.0/composite/sobjects
Content-Type: application/json

{
  "allOrNone": true,
  "records": [
    {"attributes": {"type": "Contact"}, "FirstName": "John", "LastName": "Doe"},
    {"attributes": {"type": "Contact"}, "FirstName": "Jane", "LastName": "Smith"}
  ]
}

sObject Collections Delete (batch delete)

DELETE /salesforce/services/data/v59.0/composite/sobjects?ids=003XXXXX,003YYYYY&allOrNone=true

Get Updated Records

GET /salesforce/services/data/v59.0/sobjects/{objectType}/updated/?start=2026-01-30T00:00:00Z&end=2026-02-01T00:00:00Z

Get Deleted Records

GET /salesforce/services/data/v59.0/sobjects/{objectType}/deleted/?start=2026-01-30T00:00:00Z&end=2026-02-01T00:00:00Z

Get API Limits

GET /salesforce/services/data/v59.0/limits

List API Versions

GET /salesforce/services/data/

Common Objects

• Account - Companies/Organizations
• Contact - People associated with accounts
• Lead - Potential customers
• Opportunity - Sales deals
• Case - Support cases
• Task - To-do items
• Event - Calendar events

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/salesforce/services/data/v59.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+5',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/salesforce/services/data/v59.0/query',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'q': 'SELECT Id,Name FROM Contact LIMIT 5'}
)

Notes

• Use URL encoding for SOQL queries (spaces become +)
• Record IDs are 15 or 18 character alphanumeric strings
• API version (v59.0) can be adjusted; latest is v65.0
• Update and Delete operations return HTTP 204 (no content) on success
• Dates for updated/deleted queries use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
• Use allOrNone: true in batch operations for atomic transactions
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], sort[], records[]) to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.

Error Handling

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

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

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with salesforce. For example:

• Correct: https://gateway.maton.ai/salesforce/services/data/v59.0/query
• Incorrect: https://gateway.maton.ai/services/data/v59.0/query

Resources

• REST API Developer Guide
• List sObjects
• Describe sObject
• Get Record
• Create Record
• Update Record
• Delete Record
• Query Records (SOQL)
• Composite Request
• sObject Collections
• SOQL Reference
• SOSL Reference
• Maton Community
• Maton Support