OpenClaw API Integration Skill: Build a Reliable API Workflow

An OpenClaw API integration skill is the fastest way to turn a repeated API task into something an agent can run safely. I build these when I want OpenClaw to fetch data, transform it, and create an operational artifact without hiding the real work inside a prompt.

This guide shows the pattern I use in production: a small Python client, a skill file that teaches OpenClaw when to use it, a verification command, and a recovery path. If you already understand the basics of skill folders, skim the custom OpenClaw skills developer guide first. If you are choosing between a skill and a protocol server, pair this with the OpenClaw MCP server guide.

The example uses the GitHub REST API because it is easy to test and useful immediately. The same structure works for Stripe, HubSpot, Linear, Notion, weather data, internal dashboards, or any API where the agent needs a reliable tool boundary instead of vague instructions.

Setup: create a repo-local API client

I start every integration outside OpenClaw. The agent should not be the first place an API client proves itself. Create a small workspace, a scripts directory, and a state directory for last-run artifacts.

mkdir -p openclaw-api-skill/bin openclaw-api-skill/state openclaw-api-skill/skills/github-issues cd openclaw-api-skill python3 -m venv .venv . .venv/bin/activate python3 -m pip install requests

Now create a tiny GitHub issue fetcher. It accepts owner, repo, and token from explicit places. It prints a compact report and writes the same report to disk so the next OpenClaw run has evidence to inspect.

python3 -c 'from pathlib import Path; text = """#!/usr/bin/env python3 import os import sys from pathlib import Path import requests if len(sys.argv) != 3: print("usage: github_issues.py owner repo") sys.exit(2) owner = sys.argv[1] repo = sys.argv[2] token = os.getenv("GITHUB_TOKEN") if not token: print("status=fail reason=missing_github_token") sys.exit(3) url = "https://api.github.com/repos/" + owner + "/" + repo + "/issues" headers = dict() headers["Authorization"] = "Bearer " + token headers["Accept"] = "application/vnd.github+json" params = dict(state="open", per_page=10) res = requests.get(url, headers=headers, params=params, timeout=20) if res.status_code != 200: print("status=fail http_status=" + str(res.status_code)) sys.exit(4) items = res.json() lines = ["status=ok open_issues=" + str(len(items))] for item in items[:5]: number = str(item.get("number")) title = item.get("title", "untitled").replace("\n", " ") lines.append("issue=" + number + " title=" + title) report = "\n".join(lines) + "\n" Path("state/github-issues-last-run.txt").write_text(report) print(report, end="") """; Path("bin/github_issues.py").write_text(text)' chmod +x bin/github_issues.py

This looks mundane, and that is the point. The script has a clear interface. Missing credentials fail before any network call. A non-success API response stops the run. The output is human-readable, but it is also structured enough for an agent to summarize or route into the next step.

Run it manually once with a repository you can access:

GITHUB_TOKEN=your_token_here ./bin/github_issues.py octocat Hello-World cat state/github-issues-last-run.txt

In a real setup, do not paste tokens into shell history. Use your normal secret manager or environment loader. The command above is just the minimal smoke test. Once the client works, the skill can safely describe how OpenClaw should use it.

Configuration: write the OpenClaw skill contract

A skill is not just documentation. It is a routing contract for the agent. A good OpenClaw API integration skill answers four questions: when should this skill be used, what command should run, what inputs are required, and what counts as success.

Create the skill file with direct operating rules:

python3 -c 'from pathlib import Path; text = """# GitHub Issues API Skill Use this skill when the user asks for a quick read-only summary of open GitHub issues. Inputs required: - Repository owner - Repository name - GITHUB_TOKEN available in the environment Command: . .venv/bin/activate ./bin/github_issues.py octocat Hello-World Success criteria: - Command exits zero - Output begins with status=ok - state/github-issues-last-run.txt exists and contains the latest report Failure handling: - If GITHUB_TOKEN is missing, ask for credentials setup rather than retrying - If the API returns a non-success status, report the status and stop - Do not create, close, label, or comment on issues with this skill """; Path("skills/github-issues/SKILL.md").write_text(text)' cat skills/github-issues/SKILL.md

The line I care about most is the last one: read-only. I prefer to start API integrations as read-only skills because they establish auth, schema, logging, and agent behavior before anything can mutate production. Once the read path is stable, write actions can get their own separate skill with dry-run output.

Notice that the skill does not say “use GitHub as needed.” That phrase is too wide. It tells the agent exactly what the skill does and exactly what it must not do. Good OpenClaw skills remove ambiguity.

If this skill is part of a larger toolkit, add a short README beside the scripts. It gives future agents a discovery map.

python3 -c 'from pathlib import Path; text = """# API skill commands - bin/github_issues.py: read-only issue summary using GitHub REST API - state/github-issues-last-run.txt: latest evidence file - skills/github-issues/SKILL.md: agent-facing operating contract """; Path("README.md").write_text(text)' cat README.md

Usage: run the skill inside a repeatable workflow

Once the API client and skill exist, I wrap them in one command. OpenClaw can run individual commands, but one workflow script is easier to verify, schedule, and recover.

python3 -c 'from pathlib import Path; text = """#!/usr/bin/env bash set -euo pipefail if [ $# -ne 2 ]; then echo usage: run_github_issues_workflow.sh owner repo exit 2 fi owner=$1 repo=$2 . .venv/bin/activate ./bin/github_issues.py $owner $repo printf "workflow=github_issues status=ok owner=%s repo=%s\n" $owner $repo | tee state/github-issues-workflow.txt """; Path("bin/run_github_issues_workflow.sh").write_text(text)' chmod +x bin/run_github_issues_workflow.sh GITHUB_TOKEN=your_token_here ./bin/run_github_issues_workflow.sh octocat Hello-World

The workflow does one thing: it runs the read-only issue report and writes a completion artifact. If you later schedule it with OpenClaw cron, the cron instruction can stay short: read the skill, run the workflow, inspect the state file, and only notify a human if something changed.

For scheduled work, connect this pattern to the OpenClaw cron automation guide. The important part is not the scheduler. The important part is that the skill exposes a deterministic command and a deterministic output file.

You can also use the last-run file as context for follow-up tasks. For example, OpenClaw can summarize the top issues, route bug reports to an engineering channel, or prepare a draft weekly triage note. I still keep the API client read-only unless the user explicitly asks for a write-capable workflow.

Advanced tips: add retries, dry runs, and audit logs

API integrations fail in normal ways: credentials expire, rate limits trigger, schemas shift, and networks get noisy. I do not try to solve all of that in the agent prompt. I put the boring resilience into the tool.

First, add a simple retry wrapper for transient failures. Keep it outside the client so it can be reused by other API commands.

python3 -c 'from pathlib import Path; text = """#!/usr/bin/env bash set -euo pipefail attempt=1 while [ $attempt -le 3 ]; do if "$@"; then exit 0 fi echo retry_attempt=$attempt sleep $attempt attempt=$((attempt + 1)) done echo status=fail reason=retries_exhausted exit 1 """; Path("bin/with_retry.sh").write_text(text)' chmod +x bin/with_retry.sh GITHUB_TOKEN=your_token_here ./bin/with_retry.sh ./bin/github_issues.py octocat Hello-World

Second, create a dry-run convention before you add write actions. Even for read-only workflows, dry runs are useful because they show the target and operation without touching the API.

printf '%s ' 'dry_run=true' 'operation=fetch_open_issues' 'target=octocat/Hello-World' 'writes=false' | tee state/github-issues-dry-run.txt cat state/github-issues-dry-run.txt

Third, write audit logs as plain text lines. I want something simple enough to inspect with cat, grep, or an agent summary. You can upgrade to a database later, but most teams need evidence before they need infrastructure.

mkdir -p logs printf '%s ' 'event=github_issues_run result=ok repo=octocat/Hello-World' | tee logs/audit.log cat logs/audit.log

When you move from read-only to write-capable actions, split the skill. Keep the read skill clean. Create a separate write skill with explicit approval rules, dry-run examples, and verification steps. That separation prevents a helpful agent from treating “summarize issues” and “close issues” as adjacent operations.

Troubleshooting: debug the boundary before the agent

When an OpenClaw API integration skill fails, I check the boundary first. Most failures are not reasoning failures. They are missing tokens, wrong working directories, dependency drift, or scripts that silently swallow errors.

Run the manual checks in this order:

pwd ls -la bin skills state . .venv/bin/activate python3 -c 'import requests; print("requests=ok")' python3 -c 'import os; print("token=present" if os.getenv("GITHUB_TOKEN") else "token=missing")'

If the token is missing, fix credentials. If requests is missing, reinstall dependencies in the virtual environment. If the state file is stale, run the workflow directly and inspect the exit code.

GITHUB_TOKEN=your_token_here ./bin/run_github_issues_workflow.sh octocat Hello-World echo exit_code=$? cat state/github-issues-last-run.txt

For API status failures, print the status and stop. Do not make the agent guess whether a 401, 403, 404, or 429 means the same thing. It does not. A 401 points at auth. A 403 may be permissions or rate limits. A 404 may be a repository name, private access, or endpoint issue. A 429 means back off.

The fix is almost always in the client, the environment, or the skill contract. Rewrite the prompt only after the command is honest and the skill is precise.

FAQ: OpenClaw API integration skills

What makes an API integration a good OpenClaw skill? A narrow use case, explicit inputs, deterministic commands, clear success criteria, and a failure path that tells the agent when to stop.

Should I use an MCP server instead? Use an MCP server when multiple clients need the same structured tool API. Use a skill when OpenClaw needs instructions around scripts or existing command-line tools.

How should I store API keys? Store keys in your normal secret manager or environment loader. The skill should mention required environment variables but should never contain secret values.

Can an OpenClaw skill perform write actions? Yes, but separate write actions from read actions. Add dry-run output, verification commands, and human approval for destructive or public changes.

What is the first API skill I should build? Build a read-only status or reporting skill: GitHub issues, Stripe balance summaries, calendar availability, support ticket counts, or website health checks. Prove the boundary before adding mutations.

If you want the fastest next step, build one read-only API skill today. Pick a recurring lookup, make the command work from the terminal, write the skill contract, and give OpenClaw a last-run artifact to inspect. That is the practical path from “agent can talk” to “agent can operate.”