OpenClaw Tool Executor

General-purpose tool executor for OpenClaw agents. Uses Scalekit Connect to discover and run tools for any connected service — OAuth (Notion, Slack, Gmail, GitHub, etc.) or non-OAuth (API Key, Bearer, Basic auth).

Environment Variables

Required in .env:

CODEBLOCK0

INLINECODE1 is used as the default --identifier for all operations. If not set, the script will prompt the user at runtime and display a warning advising them to set it in .env.

Execution Flow

When the user asks to perform an action on a connected service, follow these steps in order:

Step 1 — Discover the Connection

Dynamically resolve the connection_name by listing all configured connections for the provider. The API paginates automatically through all pages:

CODEBLOCK1

• - Only consider connections with "status": "COMPLETED" — ignore any with DRAFT, PENDING, or other non-completed statuses.
• Use the key_id from the first COMPLETED result as <CONNECTION_NAME> for all subsequent steps.
• If no connection found → inform the user that no <PROVIDER> connection is configured in Scalekit and stop.
• If connections exist but none are COMPLETED → inform the user of the connection key_id(s) found and tell them the connection configuration is not completed. Ask them to complete setup in the Scalekit Dashboard and stop.
• If multiple COMPLETED connections found → the first one is selected automatically (a warning is shown).

Step 2 — Check & Authorize

Run --generate-link for the connection. The tool automatically detects the connection type (OAuth vs non-OAuth) and applies the correct auth flow:

CODEBLOCK2

OAuth connections:

• - If already ACTIVE → proceed to Step 3.
• If not active → a magic link is generated. Present it to the user, wait for them to complete the flow, then proceed to Step 3.

Non-OAuth connections (BEARER, BASIC, API Key, etc.):

• - If account not found → stop. Tell the user: "Please create and configure the <CONNECTION_NAME> connection in the Scalekit Dashboard."
• If account exists but not active → stop. Tell the user: "Please activate the <CONNECTION_NAME> connection in the Scalekit Dashboard."
• If ACTIVE → proceed to Step 3.

Never use --get-authorization in the execution flow — that is only for inspecting raw OAuth tokens and does not work for non-OAuth connections.

Step 3 — Discover Available Tools

Fetch the list of tools available for the provider:

CODEBLOCK3

• - Look for a tool that matches the user's intent (e.g. notion_page_get for reading a page).
• If a matching tool exists → go to Step 3b.
• If no matching tool exists → go to Step 5 (proxy fallback).

Step 3b — Fetch Tool Schema (mandatory before executing)

Always fetch the schema of the matched tool before constructing the input. This tells you the exact parameter names, types, required vs optional fields, and valid enum values:

CODEBLOCK4

• - Read the input_schema.properties from the response — use only the parameter names defined there.
• Note which fields are in required — these must always be included in --tool-input.
• Use description and display_properties to understand what each field expects.
• Never guess parameter names — always derive them from the schema.

Step 4 — Execute the Tool

Construct the tool input using only parameters from the schema fetched in Step 3b, then run:

CODEBLOCK5

Return the result to the user.

Step 5 — Proxy Fallback (only if no tool exists)

If no Scalekit tool covers the required action, attempt a proxied HTTP request directly to the provider's API:

CODEBLOCK6

Note: Proxy may be disabled on some environments. If it returns TOOL_PROXY_DISABLED, inform the user that this action isn't supported by the current Scalekit tool catalog and suggest they request a new tool from Scalekit.

Example: Search LinkedIn (via HarvestAPI)

CODEBLOCK7

1. 1. --list-connections --provider HARVESTAPI → key_id: harvestapi-xxxx, INLINECODE25
2. INLINECODE26 → detects API_KEY, checks account → ACTIVE
3. INLINECODE27 → finds INLINECODE28

3b. --get-tool --tool-name harvestapi_search_people → schema shows valid params: first_names, last_names, search, locations, current_job_titles, etc.

1. 4. INLINECODE35

→ returns matching LinkedIn profiles

Any LinkedIn-related request (profiles, jobs, companies, posts, people search, ads, groups) → use provider HARVESTAPI.

Example: Search the web with Exa (API Key connection)

CODEBLOCK8

1. 1. --list-connections --provider EXA → key_id: exa, INLINECODE39
2. INLINECODE40 → detects API_KEY, checks account → ACTIVE
3. INLINECODE41 → finds INLINECODE42

3b. --get-tool --tool-name exa_search → schema shows query (required), num_results, type, etc.

1. 4. INLINECODE47

→ returns search results

Example: Read a Notion Page (OAuth connection)

CODEBLOCK9

1. 1. --list-connections --provider NOTION → key_id: notion-ijIQedmJ, INLINECODE50
2. INLINECODE51 → detects OAuth, already ACTIVE
3. INLINECODE52 → finds INLINECODE53

3b. --get-tool --tool-name notion_page_get → schema shows page_id (required)

1. 4. INLINECODE56

→ returns page metadata

Example: Action Not Yet in Scalekit

CODEBLOCK10

1. 1. --list-connections --provider NOTION → INLINECODE58
2. INLINECODE59 → ACTIVE
3. INLINECODE60 → no notion_blocks_fetch tool found
4. INLINECODE62 → fallback attempt
5. If proxy disabled → inform user the action isn't available yet

File Uploads & Downloads

Some providers do not have Scalekit tools for file operations. Use --proxy-request with --input-file (upload) or direct S3/CDN URL download (download). Provider-specific flows are documented below.

⚠️ Proxy token expiry: --proxy-request passes the stored OAuth access token directly to the provider. If the token has expired, the provider will return 401 Unauthorized. Unlike --execute-tool which auto-refreshes tokens, the proxy does not. If you get a 401, the token needs to be refreshed — re-run --generate-link to check status; if the connection is ACTIVE but proxy still returns 401, the user must re-authorize via a new magic link to obtain a fresh token.

---

Notion

Upload a File to a Notion Page

Notion file uploads are a 3-step process via proxy:

Step 1 — Create an upload object

CODEBLOCK11

Returns a file_upload object with an id and upload_url. The upload is valid for 1 hour.

Step 2 — Send the file

CODEBLOCK12

• - The file is sent as multipart/form-data. On success, status becomes uploaded.
• ⚠️ Notion rejects application/octet-stream. If the file extension is not recognized (e.g. .md), copy it to a .txt extension first so the MIME type resolves to text/plain.

Step 3 — Attach the file block to a page

CODEBLOCK13

Do not use notion_page_content_append for file blocks — it does not support the file_upload block type and will return an INTERNAL_ERROR. Always use the proxy for file attachment.

---

Download a File from a Notion Page

Notion files are stored on S3 with pre-signed URLs that expire in 1 hour. The download is a 2-step process:

Step 1 — Get a fresh pre-signed URL

List the page blocks to find the file block and its current URL:

CODEBLOCK14

Find the block with "type": "file" — the URL is at file.file.url. Always fetch a fresh URL; never reuse a URL from a previous response as it may be expired.

Step 2 — Download directly from S3

The S3 URL is public (pre-signed) — no Scalekit proxy needed. Download it directly:

CODEBLOCK15

Or use --output-file if going through the proxy:

CODEBLOCK16

Note: --output-file saves the raw API response (JSON block object), not the file itself. Use direct S3 download for the actual file content.

---

Google Drive

Coming soon

---

OneDrive / SharePoint

Coming soon

---

Supported Providers

Any provider configured in Scalekit (Notion, Slack, Gmail, Google Sheets, GitHub, Salesforce, HubSpot, Linear, and 50+ more). Use the provider name in uppercase for --provider (e.g. NOTION, SLACK, GOOGLE).