openclaw-tool-executor

# 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`:

```
TOOL_CLIENT_ID=<scalekit_client_id>
TOOL_CLIENT_SECRET=<scalekit_client_secret>
TOOL_ENV_URL=<scalekit_environment_url>
TOOL_IDENTIFIER=<default_identifier>   # optional but recommended
```

`TOOL_IDENTIFIER` 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:

```bash
uv run tool_exec.py --list-connections --provider <PROVIDER>
```

- 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:

```bash
uv run tool_exec.py --generate-link \
  --connection-name <CONNECTION_NAME>
```

**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:

```bash
uv run tool_exec.py --get-tool --provider <PROVIDER>
```

- 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:

```bash
uv run tool_exec.py --get-tool --tool-name <TOOL_NAME>
```

- 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:

```bash
uv run tool_exec.py --execute-tool \
  --tool-name <TOOL_NAME> \
  --connection-name <CONNECTION_NAME> \
  --tool-input '<JSON_INPUT>'
```

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:

```bash
uv run tool_exec.py --proxy-request \
  --connection-name <CONNECTION_NAME> \
  --path <API_PATH> \
  --method <GET|POST|PUT|DELETE> \
  --query-params '<JSON>' \   # optional
  --body '<JSON>'             # optional
```

> 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)

```
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` → detects API_KEY, checks account → ACTIVE
3. `--get-tool --provider HARVESTAPI` → finds `harvestapi_search_people`
3b. `--get-tool --tool-name harvestapi_search_people` → schema shows valid params: `first_names`, `last_names`, `search`, `locations`, `current_job_titles`, etc.
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"}'`
   → 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)

```
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` → detects API_KEY, checks account → ACTIVE
3. `--get-tool --provider EXA` → finds `exa_search`
3b. `--get-tool --tool-name exa_search` → schema shows `query` (required), `num_results`, `type`, etc.
4. `--execute-tool --tool-name exa_search --connection-name exa --tool-input '{"query": "latest AI news"}'`
   → returns search results

## Example: Read a Notion Page (OAuth connection)

```
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` → detects OAuth, already ACTIVE
3. `--get-tool --provider NOTION` → finds `notion_page_get`
3b. `--get-tool --tool-name notion_page_get` → schema shows `page_id` (required)
4. `--execute-tool --tool-name notion_page_get --connection-name notion-ijIQedmJ --tool-input '{"page_id": "..."}'`
   → returns page metadata

## Example: Action Not Yet in 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` → no `notion_blocks_fetch` tool found
4. `--proxy-request --path "/blocks/<page_id>/children"` → 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**

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

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

**Step 2 — Send the file**

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

- 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**

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

> 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:

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

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:

```python
import urllib.request
urllib.request.urlretrieve("<s3_url>", "/local/path/filename")
```

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

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

> 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`).