OpenClaw Docs Agent API

AI-powered documentation chatbot API for OpenClaw, built by OpenKnot.

This powers the embedded docs agent that helps users navigate and understand OpenClaw's documentation through natural conversation.

Overview

This API serves as the backend for OpenClaw's docs chat widget. It uses RAG (Retrieval-Augmented Generation) to:

1. Index OpenClaw documentation into a vector store
2. Retrieve relevant docs based on user questions
3. Stream AI-generated answers with context from the documentation

Stack

• Framework: Next.js 16 with Edge Runtime
• Runtime: Bun
• Deployment: Vercel Edge Functions
• Vector Store: Upstash Vector
• Rate Limiting: Upstash Redis
• AI: OpenAI (gpt-4.1-mini for chat, text-embedding-3-large for embeddings)
• Language: TypeScript

API Endpoints

Endpoint	Method	Description
/api/chat	POST	Send a question, get a streaming response
/api/health	GET	Health check
/api/webhook	POST	GitHub docs webhook for re-indexing

POST /api/chat

{
  "message": "How do I get started with OpenClaw?"
}

Returns a streaming text/plain response with an AI-generated answer grounded in OpenClaw documentation.

Rate Limit Headers:

• X-RateLimit-Limit - Maximum requests allowed
• X-RateLimit-Remaining - Requests remaining in window
• X-RateLimit-Reset - Timestamp when the limit resets

CORS: The API allows requests from configured origins. To add your domain, update the ALLOWED_ORIGINS array in app/api/chat/route.ts.

Setup

1. Install dependencies:

bun install

2. Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	Yes	OpenAI API key
UPSTASH_VECTOR_REST_URL	Yes	Upstash Vector endpoint
UPSTASH_VECTOR_REST_TOKEN	Yes	Upstash Vector auth token
UPSTASH_REDIS_REST_URL	Yes	Upstash Redis endpoint (rate limiting)
UPSTASH_REDIS_REST_TOKEN	Yes	Upstash Redis auth token
GITHUB_WEBHOOK_SECRET	No	Secret for GitHub webhook (required for automatic re-indexing)

3. Build the vector index (indexes documentation into Upstash):

bun run build:index

Development

bun run dev

Runs locally at http://localhost:3000.

Scripts

Script	Description
bun run dev	Start development server
bun run build	Build for production
bun run start	Start production server
bun run lint	Run ESLint
bun run build:index	Index documentation into vector store
bun run deploy	Deploy to Vercel

Deploy

bun run deploy

Deploys to Vercel.

Automatic Documentation Updates

The API supports automatic re-indexing when documentation changes are pushed to the main branch. This is powered by a GitHub webhook that triggers the /api/webhook endpoint.

How It Works

1. A push is made to the main (or master) branch of your docs repository
2. GitHub sends a webhook payload to /api/webhook
3. The API verifies the signature, fetches https://docs.openclaw.ai/llms-full.txt, chunks the content, generates embeddings, and replaces the vector store

Setting Up the Webhook

1. Set the webhook secret in your environment variables:

   GITHUB_WEBHOOK_SECRET=your-secret-here

2. Create a webhook in your docs repository:

   • Go to your docs repo → Settings → Webhooks → Add webhook
   • Payload URL: https://your-api-domain.com/api/webhook
   • Content type: application/json
   • Secret: Use the same value as GITHUB_WEBHOOK_SECRET
   • Events: Select "Just the push event"

3. Verify it's working:

   • GitHub sends a ping event when the webhook is created
   • Check the webhook's "Recent Deliveries" tab for the response
   • Push a change to main and confirm re-indexing occurs

Webhook Status

You can check the webhook status at any time:

curl https://your-api-domain.com/api/webhook

Returns the current indexing status, last indexed time, and result of the most recent indexing run.

License

MIT