The rapid evolution of AI orchestration tools has reshaped how companies build intelligent systems. Among these tools, OpenClaw has emerged as a powerful open-source platform designed to simplify the creation of AI agents, conversational workflows, and multi-channel integrations.

OpenClaw is not just another wrapper around LLM APIs. It is:

Modular
Plugin-driven
Open-source
OpenAI-compatible
Community-powered

Its OpenAI-compatible design makes it instantly interoperable with the entire AI tooling ecosystem — SDKs, automation frameworks, browser clients, bots, and custom agent pipelines.

And because it is open source, innovation happens in public.

There is an active and growing community contributing:

New plugins
Messaging integrations (WhatsApp, web, etc.)
Tool execution engines
Agent frameworks
Workflow automation patterns
Performance optimizations

This means OpenClaw evolves continuously — without vendor lock-in.

But while agility and innovation are essential, enterprises require something more:

Security
Governance
Compliance
Regional data sovereignty
Observability
Controlled network exposure
Predictable scalability

This is where Oracle Cloud Infrastructure (OCI) Generative AI becomes the strategic enterprise choice.

⸻

The Power of Ecosystem + Enterprise Security

OpenClaw: Open Ecosystem Advantage

Because OpenClaw is:

Open-source
Community-driven
Plugin-extensible
OpenAI-protocol compatible

You benefit from:

Rapid innovation
Transparent architecture
Community-tested integrations
Zero dependency on a single SaaS provider
Full customization capability

You are not locked into one AI vendor. You control your orchestration layer.

This flexibility is critical in a world where models evolve rapidly and enterprises need adaptability.

⸻

OCI Generative AI: Enterprise Trust Layer

Oracle Cloud Infrastructure adds what large organizations require:

Fine-grained IAM control
Signed API requests (no exposed API keys)
Dedicated compartments
Private VCN networking
Sovereign cloud regions
Enterprise SLAs
Monitoring & logging integration
Production-ready inference endpoints

OCI Generative AI supports powerful production-grade models such as:

Cohere Command
LLaMA family
Embedding models
Custom enterprise deployments
OpenAI-compatible models via mapping

This creates a secure AI backbone inside your own tenancy.

⸻

Why This Combination Is Strategically Powerful

By implementing a local OpenAI-compatible gateway backed by OCI:

OpenClaw continues to behave exactly as designed — while inference happens securely inside Oracle Cloud.

You gain:

Full OpenAI protocol compatibility
Enterprise security boundaries
Cloud tenancy governance
Scalable AI inference
Ecosystem extensibility
Open-source flexibility

Without rewriting your agents. Without breaking plugins. Without sacrificing innovation.

⸻

About the tutorial

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-5": "openai.gpt-4.1",
    "openai/gpt-5": "openai.gpt-4.1",
    "openai-compatible/gpt-5": "openai.gpt-4.1",
}

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": "gpt-5"
  },
  "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-5",
    "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-5",
                "name": "gpt-5" ,
                "reasoning": false,
                "input": ["text"],
                "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
                "contextWindow": 200000,
                "maxTokens": 8192
              }
            ]
         }
      }
   },
   "agents":{
      "defaults":{
         "model":{
           "primary": "openai-compatible/gpt-5"
         }
      }
   },
   "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)

README.md Unescape Escape

Integrating OpenClaw with Oracle Cloud Generative AI (OCI)

Enterprise AI Power, Open Ecosystem, Zero Compromise

The Power of Ecosystem + Enterprise Security

OpenClaw: Open Ecosystem Advantage

OCI Generative AI: Enterprise Trust Layer

Why This Combination Is Strategically Powerful

About the tutorial

Why Use OCI Generative AI?

Architecture

Project Structure

Key Code Sections Explained

1️⃣ Configuration Section

What it does:

2️⃣ Model Mapping

Why this is important:

3️⃣ Pydantic OpenAI-Compatible Request Model

Purpose:

4️⃣ OCI Signer

Purpose:

5️⃣ Message Conversion (OpenAI → OCI Format)

6️⃣ OCI REST Call

7️⃣ Streaming Implementation

8️⃣ OpenAI-Compatible Response Builder

Running the Server

Testing with curl

OpenClaw Configuration (openclaw.json)

Important Fields

Final Notes

Reference

Acknowledgments

README.md