Agent Docs

Connect an agent to KOL.Tools

This guide is for agents and integrators that need to call KOL.Tools directly. The goal is to bind access safely, create jobs, and avoid duplicate billing or bad retries.

Back to Learn Open OpenClaw page

Goal

Connect to KOL.Tools safely without asking for passwords, generate multi-platform content packs from a URL or topic, and default to English output unless the user requests Chinese.

Security rules

Do not ask for credentials, do not ask the user to run terminal commands, do not send tokens outside kol.tools, and stop immediately with a clear reason if fetching fails.

One-time connection flow

1Call POST /api/openclaw/agents/init to get agent_id, claim_url, and poll_token.
2Ask the user to open claim_url, sign in, and click Bind.
3Poll GET /api/openclaw/agents/{agent_id}?poll_token=... until status = "bound".
4After you receive agent_access_token, create packs jobs.

API basics

The base URL is https://kol.tools and both requests and responses use JSON.

Key endpoints

1. Initialize an agent

Request

POST https://kol.tools/api/openclaw/agents/init
Content-Type: application/json

{
  "client": "openclaw",
  "agent_name": "optional",
  "agent_fingerprint": "optional"
}

Response

{
  "agent_id": "agt_123",
  "claim_url": "https://kol.tools/claim/claim_abc",
  "poll_token": "poll_abc",
  "expires_at": "2026-02-12T00:00:00Z"
}

2. Poll binding status

Request

GET https://kol.tools/api/openclaw/agents/agt_123?poll_token=poll_abc

Response

{
  "agent_id": "agt_123",
  "status": "bound",
  "agent_access_token": "token_xxx"
}

3. Create a link_pack job

Request

POST https://kol.tools/api/packs/jobs
Authorization: Bearer token_xxx
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "type": "link_pack",
  "input": {
    "url": "https://example.com",
    "platforms": ["x", "xiaohongshu", "bilibili", "youtube", "instagram", "linkedin", "tiktok", "threads"],
    "tone": "casual",
    "language": "en"
  },
  "options": {
    "images": { "count": 3, "ratios": ["1:1", "9:16", "16:9"] }
  }
}

Response

{
  "job_id": "job_123",
  "status": "queued"
}

Polling and retry rules

• Poll every 2 seconds for the first 20 seconds, then every 5 seconds.
• If the agent is still not bound after 2 minutes, stop and ask the user to reopen the claim link.
• Reuse the same Idempotency-Key for the same user request to avoid duplicate billing.
• If the result is incomplete, retry at most once.

User-readable errors

• FETCH_FAILED: the target URL could not be fetched. Ask for a new URL or a manual summary.
• NO_CREDITS: the account has no credits left. Redirect the user to pricing or recharge.
• RATE_LIMIT: rate limiting is active. Ask the user to retry later and avoid tight loops.