Building agent-friendly APIs: lessons from shipping OpenClaw

An API designed for humans and an API designed for agents pull in opposite directions on at least five dimensions. Here's what we learned shipping the OpenClaw CLI.

1. Default to structured output, not human-readable

Human-friendly APIs lean into colored terminal output, progress bars, ASCII tables. Agent-friendly APIs return JSON-by-default and only show pretty output when stdout is a TTY. Every OpenClaw command outputs JSON unless you pass --pretty. Agents never have to ask for the structured shape.

2. Stable response shapes across versions

When an LLM has memorized your response schema, breaking it costs you more than breaking a human SDK does. Humans read changelogs; LLMs read context windows. We version the response shape and never silently drop or rename fields — additions only.

3. Error messages that explain the next action

A good agent error message includes both the cause and the recommended action. "Auth failed: COLLABPAL_API_KEY missing — set it via `export COLLABPAL_API_KEY=...` or pass --api-key." An agent can act on that. A bare "Unauthorized" forces the agent to guess.

4. Read-only and write-only modes

Agents are powerful and occasionally wrong. Letting an agent run `openclaw audit` is fine — it just reads. Letting an agent run `openclaw delete` or `openclaw billing:cancel` without a confirmation step is reckless. We mark write operations explicitly and require a `--confirm` flag.

5. Discoverability via SKILL.md

Agents need to learn what your tool can do without reading prose docs. We ship a SKILL.md file in the package that lists every command, every flag, and every response field in a flat, parseable structure. Agents read it once and never ask again. Documentation that's actually executable.

The TL;DR test

If your API requires a 5-minute SDK README to use, an agent will struggle. If it requires a 30-line SKILL.md and a few clean examples, an agent will be productive immediately. The bar for agent-friendly is unfortunately higher than the bar for human-friendly — but the upside is your tool gets used in workflows you didn't anticipate.