# Integrating OpenClaw with Oracle Cloud Generative AI (OCI) ## Enterprise AI Power, Open Ecosystem, Zero Compromise 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 ``` python 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 ``` python 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 ``` python 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 ``` python 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) ``` python 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 ``` python 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 ``` python 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 ``` python 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: ```json { "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 ```table 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 - [Installing the OCI CLI](https://docs.oracle.com/en-us/iaas/private-cloud-appliance/pca/installing-the-oci-cli.htm) - [Oracle Cloud Generative AI](https://www.oracle.com/artificial-intelligence/generative-ai/generative-ai-service/) - [OpenClaw](https://openclaw.ai/) # Acknowledgments - **Author** - Cristiano Hoshikawa (Oracle LAD A-Team Solution Engineer)