---
name: ai_proxy_skill
description: Use when working with this ai-agent-proxy project, especially to understand its HTTP endpoints, inbox-driven worker flow, and how requests are delivered to the local agent inbox.
---

# AI Proxy Skill

Use this skill when you are working inside this `ai-agent-proxy` project.

## Project Model

This project is an inbox-driven proxy.

- HTTP requests are accepted by the FastAPI server.
- The server writes the request JSON body into the local agent inbox.
- The worker should listen to the inbox and process pending files.
- Replies should follow the message instructions in the inbox item.

## Inbox Flow

- The worker inbox path is under the local workspace for this project.
- Listen to the inbox folder for new files.
- Read each inbox file as JSON.
- Process one inbox item at a time.
- After finishing one item, check the inbox again.
- When idle, keep checking the inbox files while waiting.

## Endpoints

### `POST /v1/chat/completions`

Use this endpoint for chat-style requests.

- The server accepts the JSON request body.
- If no backend URL is configured, the server writes the JSON body into the inbox and returns an empty chat-completion response immediately.
- If a backend URL is configured, the server forwards the request to the backend, returns the backend response, and also writes the request JSON into the inbox with the backend reply attached.
- If `stream=true`, the response is returned as SSE.

### `GET /v1/models`

Returns the backend model list when a backend URL is configured.

If no backend URL is configured, it returns the single local proxy model.

### `GET /v1/models/{model_id}`

Returns metadata for the requested model id.

## Worker Guidance

- Listen to the inbox.
- Treat inbox files as the work queue.
- Read the JSON body carefully.
- Figure out from the inbox content what the task is.
- Decide by yourself how to reply based on the inbox content and the current project context.
- Use the OpenClaw message CLI skill to send the reply.
- When building context for a large reply, use the context cache skill first.

## Current Contract

- The inbox file content is raw JSON only.
- Inbox file names are `<timestamp>-<uuid>.json`.
- If a backend reply exists, read `backend-llm-reply` from the JSON body.
- If you need `channel` or `target` for outbound delivery, read them from the JSON body.
