ai-agent-proxy 2.3.0

Mailbox-backed AI agent proxy server

ai-agent-proxy

ai-agent-proxy is a small FastAPI service that accepts OpenAI-style requests, optionally relays them to a backend LLM, and writes inbox JSON for a local agent runtime to handle.

This package exposes one CLI:

• ai-agent-proxy for the HTTP server

It is designed for a local workspace flow:

• the API receives a request
• the request JSON is written into the agent inbox
• your local agent runtime handles it

Features

• enqueue-only quick-release HTTP flow
• optional backend LLM relay with backend reply capture
• local inbox JSON output for agent runtimes
• context_id extraction and compact follow-up inbox payloads
• better OpenClaw responsiveness while long agent work is still running
• batch-friendly message flow for ongoing conversations
• pure local runtime design, so you can use the agent CLI you prefer

Yes / No

Yes:

• this package is for the OpenClaw OpenAI-compatible backend API flow
• it accepts OpenAI-style chat requests and turns them into local inbox work for the agent, which helps OpenClaw handle incoming messages more responsively
• when new messages arrive while the agent is already working, the agent can learn about the later messages before replying to the original one, if time permits
• it can forward requests to a backend LLM and still write the enriched request into the inbox
• the agent is expected to use tools and skills to send the real reply outward

No:

• this is not a general OpenAI endpoint replacement
• this endpoint does not return the final assistant result in the HTTP response
• it is not intended for clients that expect normal synchronous OpenAI chat completion behavior

Install

pip install ai-agent-proxy

After install, the main commands are:

ai-agent-proxy

Config

Proxy default config file: ./.ai-agent-proxy.conf

HOST=0.0.0.0
PORT=7011
KEY=aibot_<your-key-something>
WORKER=2
INBOX=~/.openclaw/workspace/inbox
URL=https://backend-llm.example.com/v1
API_KEY=sk_<your-backend-api-key>

API

This is an enqueue-only, quick-release API design intended to improve OpenClaw message handling throughput and give the agent room for batch processing.

• POST /v1/chat/completions
• GET /v1/models
• GET /v1/models/{model_id}

For request endpoints, the server writes the request body into the local inbox and returns an immediate reply to release the HTTP connection. If stream: true is used, the response is returned as SSE.

How It Works

Important local workspace paths:

• inbox: <workspace>/inbox

Inbox files are raw JSON only. There is no extra mailbox wrapper.

On chat requests:

• if no backend LLM is configured, the proxy writes the request JSON into the inbox and returns an empty success response
• if a backend LLM is configured, the proxy forwards the request, returns the backend response to the client, and also writes the request into the inbox
• when a backend reply is available, the inbox JSON can include backend-llm-reply
• when a context_id is found, repeated messages may be compacted for lighter inbox traffic

A separate local agent runtime can watch the inbox and handle the work.

Skills

Project skills live in ai_agent_proxy/skills/.

They describe:

• the proxy workflow
• outbound message delivery
• context handling

Logs

Useful server log lines:

• chat_completion request inbox file_size=... inbox_path=...
• backend_forward_failed ...
• invalid_json ...

Any agent-side logging depends on the runtime you choose.