ai-proxy-skill

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 /chat/completions

Use this endpoint for chat-style requests.

• The server accepts the JSON request body.
• The server enqueues only the JSON body into the agent inbox.
• The server returns an empty chat-completion response immediately.
• If stream=true, the server returns an SSE-formatted empty completion response.

POST /v1/chat/completions

This is the OpenAI-style alias for /chat/completions.

• Behavior is the same as /chat/completions.
• The request body is written to the inbox as JSON only.

POST /agent-inbox

Use this endpoint for direct agent-to-agent inbox delivery.

• The server accepts a JSON body with fields such as agent_id, reply_instruction, system_instruction, prompt, and a2a_key.
• The server enqueues the JSON body into the agent inbox.
• The server returns a small JSON acknowledgement immediately.

GET /v1/models

Returns the single advertised 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.
• Do not assume chat requests carry a derived channel id.
• If you need channel or target for outbound delivery, read them from the JSON body.