7.4 KiB
Integrating OpenClaw with Oracle Cloud Generative AI (OCI)
Overview
This tutorial explains how to integrate OpenClaw with Oracle Cloud Infrastructure (OCI) Generative AI by building an OpenAI-compatible API gateway using FastAPI.
Instead of modifying OpenClaw's core, we expose an OpenAI-compatible
endpoint (/v1/chat/completions) that internally routes requests to
OCI Generative AI.
This approach provides:
- ✅ Full OpenClaw compatibility
- ✅ Control over OCI model mapping
- ✅ Support for streaming responses
- ✅ Enterprise-grade OCI infrastructure
- ✅ Secure request signing via OCI SDK
Why Use OCI Generative AI?
Oracle Cloud Infrastructure provides:
- Enterprise security (IAM, compartments, VCN)
- Flexible model serving (ON_DEMAND, Dedicated)
- High scalability
- Cost control
- Regional deployment control
- Native integration with Oracle ecosystem
By building an OpenAI-compatible proxy, we combine:
OpenClaw flexibility + OCI enterprise power
Architecture
OpenClaw ↓ OpenAI-Compatible Gateway (FastAPI) ↓ OCI Generative AI REST API (20231130) ↓ OCI Hosted LLM
Project Structure
project/
├── oci_openai_proxy.py
├── README.md
Key Code Sections Explained
1️⃣ Configuration Section
OCI_CONFIG_FILE = os.getenv("OCI_CONFIG_FILE", os.path.expanduser("~/.oci/config"))
OCI_PROFILE = os.getenv("OCI_PROFILE", "DEFAULT")
OCI_COMPARTMENT_ID = os.getenv("OCI_COMPARTMENT_ID", "...")
OCI_GENAI_ENDPOINT = os.getenv(
"OCI_GENAI_ENDPOINT",
"https://inference.generativeai.us-chicago-1.oci.oraclecloud.com"
)
What it does:
- Reads OCI authentication config
- Defines target compartment
- Defines the OCI inference endpoint
2️⃣ Model Mapping
MODEL_MAP = {
"gpt-4o-mini": "openai.gpt-4.1",
"text-embedding-3-small": "cohere.embed-multilingual-v3.0",
}
Why this is important:
OpenClaw expects OpenAI model names.
OCI uses different model IDs.
This dictionary translates between them.
3️⃣ Pydantic OpenAI-Compatible Request Model
class ChatRequest(BaseModel):
model: str
messages: List[Message]
temperature: Optional[float] = None
max_tokens: Optional[int] = None
stream: Optional[bool] = False
Purpose:
Defines a request format fully compatible with OpenAI's API.
4️⃣ OCI Signer
def get_signer():
config = oci.config.from_file(OCI_CONFIG_FILE, OCI_PROFILE)
signer = oci.signer.Signer(
tenancy=config["tenancy"],
user=config["user"],
fingerprint=config["fingerprint"],
private_key_file_location=config["key_file"],
pass_phrase=config.get("pass_phrase"),
)
return signer
Purpose:
Creates a signed request for OCI REST calls.
Without this, OCI rejects the request.
5️⃣ Message Conversion (OpenAI → OCI Format)
def openai_to_oci_messages(messages: list, model_id: str) -> list:
OCI expects:
{
"role": "USER",
"content": [
{"type": "TEXT", "text": "..."}
]
}
OpenAI sends:
{ "role": "user", "content": "..." }
This function converts formats.
6️⃣ OCI REST Call
url = f"{OCI_GENAI_ENDPOINT}/20231130/actions/chat"
We use OCI's REST endpoint:
POST /20231130/actions/chat
Payload structure:
{
"compartmentId": "...",
"servingMode": {
"servingType": "ON_DEMAND",
"modelId": "openai.gpt-4.1"
},
"chatRequest": {
"apiFormat": "GENERIC",
"messages": [...],
"maxTokens": 512
}
}
7️⃣ Streaming Implementation
def fake_stream(text: str, model: str):
Since OCI GENERIC mode returns full response (not streaming), we simulate OpenAI streaming by splitting the response into chunks.
This keeps OpenClaw fully compatible.
8️⃣ OpenAI-Compatible Response Builder
def build_openai_response(model: str, text: str)
Formats the OCI response to match OpenAI's schema:
{
"id": "...",
"object": "chat.completion",
"choices": [...]
}
Running the Server
Install dependencies:
pip install fastapi uvicorn requests oci pydantic
Run:
uvicorn oci_openai_proxy:app --host 0.0.0.0 --port 8050
Testing with curl
curl http://127.0.0.1:8050/v1/chat/completions -H "Content-Type: application/json" -d '{
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Hello"}
]
}'
OpenClaw Configuration (openclaw.json)
Edit your openclaw.json configuration file (normaly it's in ~/.openclaw/openclaw.json) and replace models and agents definitions with:
{
"models":{
"providers":{
"openai-compatible":{
"baseUrl":"http://127.0.0.1:8050/v1",
"apiKey":"sk-test",
"api":"openai-completions",
"models":[
{
"id":"gpt-4o-mini",
"name":"gpt-4o-mini",
"reasoning":false,
"input":[
"text"
],
"contextWindow":200000,
"maxTokens":8192
}
]
}
}
},
"agents":{
"defaults":{
"model":{
"primary":"openai-compatible/gpt-4o-mini"
}
}
},
"gateway":{
"port":18789,
"mode":"local",
"bind":"loopback"
}
}
Important Fields
Field Purpose
--------------- --------------------------------
baseUrl Points OpenClaw to our gateway
api Must be openai-completions
model id Must match MODEL_MAP key
contextWindow Model context size
maxTokens Max response tokens
Final Notes
You now have:
✔ OpenClaw fully integrated
✔ OCI Generative AI backend
✔ Streaming compatibility
✔ Enterprise-ready architecture
Reference
Acknowledgments
- Author - Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)