mirror of
https://github.com/hoshikawa2/openclaw-oci.git
synced 2026-03-03 16:09:35 +00:00
423 lines
10 KiB
Markdown
423 lines
10 KiB
Markdown
# 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-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
|
||
|
||
``` 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": "gpt-5"
|
||
},
|
||
"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-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:
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```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)
|