OpenClaw 工具执行器

面向 OpenClaw 智能体的通用工具执行器。使用 Scalekit Connect 发现并运行任意已连接服务的工具——包括 OAuth 类服务（Notion、Slack、Gmail、GitHub 等）和非 OAuth 类服务（API Key、Bearer、Basic 认证等）。

环境变量

需在 .env 文件中配置：

TOOL_CLIENT_ID=
TOOL_CLIENT_SECRET=
TOOL_ENV_URL=
TOOL_IDENTIFIER=   # 可选，但强烈推荐设置

TOOL_IDENTIFIER 将作为所有操作的默认 --identifier 值。若未设置，脚本将在运行时提示用户输入，并显示警告，建议其在 .env 中配置该值。

执行流程

当用户请求对某已连接服务执行操作时，请**严格按以下顺序**执行：

步骤 1 — 发现连接

通过列出该服务商下所有已配置的连接，动态解析 connection_name。API 会自动分页遍历全部结果：

uv run tool_exec.py --list-connections --provider 

• 仅考虑状态为 "status": "COMPLETED" 的连接；忽略所有状态为 DRAFT、PENDING 或其他非完成状态的连接。
• 将首个 COMPLETED 结果中的 key_id 用作后续所有步骤的 。
• 若未找到任何连接 → 告知用户 Scalekit 中尚未配置 连接，并终止流程。
• 若存在连接但均未完成 → 向用户说明已发现的连接 key_id(s)，并告知其连接配置尚未完成；请用户前往 Scalekit Dashboard 完成配置后重试，并终止流程。
• 若存在多个 COMPLETED 连接 → 自动选择第一个（同时输出警告）。

步骤 2 — 检查并授权

对目标连接执行 --generate-link。工具将自动识别连接类型（OAuth 或非 OAuth），并应用对应认证流程：

uv run tool_exec.py --generate-link 
  --connection-name 

OAuth 连接：

• 若已处于 ACTIVE 状态 → 直接进入步骤 3。
• 若未激活 → 生成魔法链接（magic link）。向用户提供该链接，等待其完成授权流程后，再进入步骤 3。

非 OAuth 连接（BEARER、BASIC、API Key 等）：

• 若账户未找到 → 终止流程，并提示用户：“请在 Scalekit Dashboard 中创建并配置 连接。”
• 若账户存在但未激活 → 终止流程，并提示用户：“请在 Scalekit Dashboard 中激活 连接。”
• 若处于 ACTIVE 状态 → 进入步骤 3。

执行流程中**禁止使用** --get-authorization —— 该参数仅用于查看原始 OAuth token，且不适用于非 OAuth 连接。

步骤 3 — 发现可用工具

获取该服务商支持的所有工具列表：

uv run tool_exec.py --get-tool --provider 

• 查找与用户意图匹配的工具（例如：读取页面应匹配 notion_page_get）。
• 若存在匹配工具 → 进入步骤 3b。
• 若无匹配工具 → 进入步骤 5（代理回退）。

步骤 3b — 获取工具 Schema（执行前必做）

必须始终在构造输入前，先获取匹配工具的 Schema。该 Schema 明确指定了参数名、类型、必填/可选字段及合法枚举值：

uv run tool_exec.py --get-tool --tool-name 

• 从响应中读取 input_schema.properties —— **仅使用**其中定义的参数名。
• 注意 required 字段列表 —— 这些字段必须始终包含在 --tool-input 中。
• 参考 description 和 display_properties 理解各字段预期内容。
• 严禁猜测参数名 —— 所有参数名必须严格源自 Schema。

步骤 4 — 执行工具

仅使用步骤 3b 中获取的 Schema 所定义的参数构造工具输入，然后执行：

uv run tool_exec.py --execute-tool 
  --tool-name  
  --connection-name  
  --tool-input ''

将执行结果返回给用户。

步骤 5 — 代理回退（仅当无对应工具时启用）

若 Scalekit 当前无覆盖所需操作的工具，则尝试通过代理直接向服务商 API 发起 HTTP 请求：

uv run tool_exec.py --proxy-request 
  --connection-name  
  --path  
  --method  
  --query-params ''    # 可选
  --body ''             # 可选

注意：部分环境中代理功能可能被禁用。若返回错误码 TOOL_PROXY_DISABLED，请告知用户当前 Scalekit 工具目录暂不支持该操作，并建议其向 Scalekit 提出新工具需求。

示例：通过 HarvestAPI 搜索 LinkedIn

User: "Find software engineers in San Francisco on LinkedIn"

1. --list-connections --provider HARVESTAPI → 得到 key_id: harvestapi-xxxx，type: API_KEY
2. --generate-link --connection-name harvestapi-xxxx → 识别为 API_KEY 类型，检查账户状态 → ACTIVE
3. --get-tool --provider HARVESTAPI → 找到 harvestapi_search_people 3b. --get-tool --tool-name harvestapi_search_people → Schema 显示合法参数包括：first_names、last_names、search、locations、current_job_titles 等。
4. --execute-tool --tool-name harvestapi_search_people --connection-name harvestapi-xxxx --tool-input '{"first_names": "John", "locations": "San Francisco", "current_job_titles": "Software Engineer"}' → 返回匹配的 LinkedIn 个人资料

所有与 LinkedIn 相关的请求（个人资料、职位、公司、帖子、人员搜索、广告、群组）→ 均使用提供商 HARVESTAPI。

示例：使用 Exa（API Key 连接）进行网页搜索

User: "Search for latest AI news using Exa"

1. --list-connections --provider EXA → 得到 key_id: exa，type: API_KEY
2. --generate-link --connection-name exa → 识别为 API_KEY 类型，检查账户状态 → ACTIVE
3. --get-tool --provider EXA → 找到 exa_search 3b. --get-tool --tool-name exa_search → Schema 显示 query（必填）、num_results、type 等参数。
4. --execute-tool --tool-name exa_search --connection-name exa --tool-input '{"query": "latest AI news"}' → 返回搜索结果

示例：读取 Notion 页面（OAuth 连接）

User: "Read my Notion page https://notion.so/..."

1. --list-connections --provider NOTION → 得到 key_id: notion-ijIQedmJ，type: OAUTH
2. --generate-link --connection-name notion-ijIQedmJ → 识别为 OAuth 类型，已处于 ACTIVE 状态
3. --get-tool --provider NOTION → 找到 notion_page_get 3b. --get-tool --tool-name notion_page_get → Schema 显示 page_id（必填）
4. --execute-tool --tool-name notion_page_get --connection-name notion-ijIQedmJ --tool-input '{"page_id": "..."}' → 返回页面元数据

示例：当前 Scalekit 尚未支持的操作

User: "Fetch the blocks of a Notion page"

1. --list-connections --provider NOTION → 得到 key_id: notion-ijIQedmJ
2. --generate-link --connection-name notion-ijIQedmJ → 状态为 ACTIVE
3. --get-tool --provider NOTION → 未找到 notion_blocks_fetch 工具
4. --proxy-request --path "/blocks//children" → 启动代理回退尝试
5. 若代理被禁用 → 告知用户该操作当前尚不可用

文件上传与下载

部分服务商暂无 Scalekit 工具支持文件操作。此时应使用 --proxy-request 配合 --input-file（上传）或直接通过 S3/CDN URL 下载（下载）。各服务商的具体流程详见下方说明。

⚠️ 代理 Token 过期问题：--proxy-request 会将存储的 OAuth 访问令牌直接透传至服务商。若该 Token 已过期，服务商将返回 401 Unauthorized。与 --execute-tool（可自动刷新 Token）不同，代理机制**不具备自动刷新能力**。若收到 401 错误，表明 Token 需要刷新 —— 请重新运行 --generate-link 检查连接状态；若连接仍显示 ACTIVE 但代理持续返回 401，则用户需通过新的魔法链接重新授权，以获取有效 Token。

Notion

向 Notion 页面上传文件

Notion 文件上传需通过代理完成三步流程：

步骤 1 — 创建上传对象

uv run tool_exec.py --proxy-request 
  --connection-name  
  --path "/v1/file_uploads" 
  --method POST 
  --body '{"mode": "single_part"}' 
  --headers '{"Notion-Version": "2022-06-28", "Content-Type": "application/json"}'

返回一个 file_upload 对象，含 id 和 upload_url。该上传链接有效期为1 小时。

步骤 2 — 发送文件

uv run tool_exec.py --proxy-request 
  --connection-name  
  --path "/v1/file_uploads//send" 
  --method POST 
  --input-file /path/to/file 
  --headers '{"Notion-Version": "2022-06-28"}'

• 文件以 multipart/form-data 格式发送。成功后，status 字段变为 uploaded。
• ⚠️ Notion 拒绝 application/octet-stream 类型。若文件扩展名未被识别（如 .md），请先将其复制为 .txt 扩展名，使 MIME 类型解析为 text/plain。

步骤 3 — 将文件块附加至页面

uv run tool_exec.py --proxy-request 
  --connection-name  
  --path "/v1/blocks//children" 
  --method PATCH 
  --body '{
    "children": [{
      "object": "block",
      "type": "file",
      "file": {
        "type": "file_upload",
        "file_upload": {"id": ""},
        "name": ""
      }
    }]
  }' 
  --headers '{"Notion-Version": "2022-06-28", "Content-Type": "application/json"}'

切勿使用 notion_page_content_append 添加文件块 —— 该工具不支持 file_upload 块类型，将返回 INTERNAL_ERROR。文件附加操作必须始终通过代理完成。

从 Notion 页面下载文件

Notion 文件存储于 S3，其预签名 URL 有效期为1 小时。下载需两步完成：

步骤 1 — 获取最新预签名 URL

列出页面区块以定位文件块及其当前 URL：

uv run tool_exec.py --proxy-request 
  --connection-name  
  --path "/v1/blocks//children" 
  --method GET 
  --headers '{"Notion-Version": "2022-06-28"}'

查找 "type": "file" 的区块 —— 其 URL 位于 file.file.url。务必每次获取全新 URL；切勿复用先前响应中的 URL（可能已过期）。

步骤 2 — 直接从 S3 下载

S3 URL 为公开预签名链接 —— 无需经 Scalekit 代理。可直接下载：

import urllib.request
urllib.request.urlretrieve("", "/local/path/filename")

或通过代理配合 --output-file 参数：

uv run tool_exec.py --proxy-request 
  --connection-name  
  --path "/v1/blocks/" 
  --method GET 
  --headers '{"Notion-Version": "2022-06-28"}' 
  --output-file /local/path/filename

注意：--output-file 保存的是原始 API 响应（JSON 区块对象），而非文件本身。如需实际文件内容，请使用直接 S3 下载方式。

Google Drive

即将上线

OneDrive / SharePoint

即将上线

支持的服务商

Scalekit 中已配置的所有服务商（Notion、Slack、Gmail、Google Sheets、GitHub、Salesforce、HubSpot、Linear 等 50+ 个）。在 --provider 参数中使用大写服务商名称（例如：NOTION、SLACK、GOOGLE）。