OpenClaw Codex Setup Guide
Connect through Lumecoder's OpenAI Responses-compatible endpoint
Register a Lumecoder Codex custom provider in OpenClaw, then configure the API key, model allowlist, default model, and verification flow.
How do you use Codex with OpenClaw?
This guide uses a custom provider: register Lumecoder's OpenAI Responses-compatible endpoint in openclaw.json, add an API key and default Codex model, then restart the gateway and verify it.
- Register the lumecoder-openai provider
- Set api to openai-responses and add the API key
- Select a default model, restart the gateway, and send a test message
Lumecoder is a third-party compatible access service, not an official OpenAI product. Model names are used only to identify compatible configuration; actual model, pricing, and access availability depend on upstream providers, platform status, and compliance requirements.
Choose the Codex connection method first
OpenClaw's built-in OpenAI Codex authentication and the Lumecoder-compatible provider described here are separate paths. Do not mix their credentials.
Built-in OpenAI Codex authentication
Follow the official authentication flow for your installed OpenClaw version. Commands and availability can change between releases.
Lumecoder-compatible provider
Continue with this guide to configure an API key, baseUrl, and openai-responses without using OpenClaw's built-in OAuth credentials.
Prerequisites
- OpenClaw installed (see OpenClaw + Lumecoder Integration Guide)
- Lumecoder account with API Key (starts with sk-)
How It Works
OpenClaw natively supports the OpenAI Responses protocol. Register a custom Provider in openclaw.json, point baseUrl to the Lumecoder API root, and set api: openai-responses.
Configuration Steps
Edit openclaw.json to add Lumecoder OpenAI Provider
Open the config file:
vim ~/.openclaw/openclaw.json
Add a top-level models node (same level as agents, channels):
"models": {
"providers": {
"lumecoder-openai": {
"baseUrl": "https://api.lumecoder.com",
"apiKey": "sk-xxx",
"api": "openai-responses",
"models": [
{
"id": "gpt-5.4",
"name": "GPT-5.4",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.3-codex",
"name": "GPT-5.3 Codex",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.2-codex",
"name": "GPT-5.2 Codex",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.1-codex-max",
"name": "GPT-5.1 Codex Max",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.2",
"name": "GPT-5.2",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.1-codex-mini",
"name": "GPT-5.1 Codex Mini",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
}
]
}
}
}Also update the model allowlist in agents.defaults:
"model": {
"primary": "lumecoder-openai/gpt-5.3-codex",
"fallbacks": []
},
"models": {
"lumecoder-openai/gpt-5.4": {},
"lumecoder-openai/gpt-5.3-codex": {},
"lumecoder-openai/gpt-5.2-codex": {},
"lumecoder-openai/gpt-5.1-codex-max": {},
"lumecoder-openai/gpt-5.2": {},
"lumecoder-openai/gpt-5.1-codex-mini": {}
}Verification
Run a test command:
openclaw agent --local --session-id test -m "你好"
If you receive a normal response, it means:
- OpenClaw is connected to Lumecoder Codex via OpenAI Responses
- Credits billing is working
- Ready for chat, code generation, and automation
Available Models
You can configure the following model in openclaw.json:
| Model ID | Description | Recommended Use |
|---|---|---|
| gpt-5.4 | Latest general-purpose frontier model, strongest overall | Chat, reasoning & coding (newest) |
| gpt-5.3-codex | Latest frontier agentic coding model | Code generation, automation (recommended) |
| gpt-5.2-codex | Frontier agentic coding model | General coding tasks |
| gpt-5.1-codex-max | Codex-optimized flagship for deep and fast reasoning | High-complexity tasks |
| gpt-5.2 | Frontier model with improvements across knowledge, reasoning and coding | General-purpose scenarios |
| gpt-5.1-codex-mini | Codex-optimized, cheaper and faster but less capable | Low-cost batch work |
Switch default model:
openclaw models set lumecoder-openai/gpt-5.2-codex
Full Configuration Reference
Complete Lumecoder Codex configuration snippet for openclaw.json:
{
"agents": {
"defaults": {
"model": {
"primary": "lumecoder-openai/gpt-5.3-codex",
"fallbacks": []
},
"models": {
"lumecoder-openai/gpt-5.4": {},
"lumecoder-openai/gpt-5.3-codex": {},
"lumecoder-openai/gpt-5.2-codex": {},
"lumecoder-openai/gpt-5.1-codex-max": {},
"lumecoder-openai/gpt-5.2": {},
"lumecoder-openai/gpt-5.1-codex-mini": {}
},
"workspace": "/home/ubuntu/.openclaw/workspace",
"compaction": { "mode": "safeguard" },
"maxConcurrent": 4,
"subagents": { "maxConcurrent": 8 }
}
},
"models": {
"providers": {
"lumecoder-openai": {
"baseUrl": "https://api.lumecoder.com",
"apiKey": "sk-xxx",
"api": "openai-responses",
"models": [
{
"id": "gpt-5.4",
"name": "GPT-5.4",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.3-codex",
"name": "GPT-5.3 Codex",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.2-codex",
"name": "GPT-5.2 Codex",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.1-codex-max",
"name": "GPT-5.1 Codex Max",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.2",
"name": "GPT-5.2",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
},
{
"id": "gpt-5.1-codex-mini",
"name": "GPT-5.1 Codex Mini",
"reasoning": false,
"input": ["text", "image"],
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 200000,
"maxTokens": 8192
}
]
}
}
}
}Troubleshooting
Invalid key format
Lumecoder API Key must start with sk-. Check the providers.lumecoder-openai.apiKey value in openclaw.json.
Config changes not taking effect
You must restart after modifying openclaw.json:
openclaw gateway restart
Provider or model name not found
Make sure the provider name exactly matches the prefix in agents.defaults.model.primary and that the model is also present in the agents.defaults.models allowlist.
Codex OAuth or API key?
The Lumecoder custom provider on this page uses an API key. If you choose OpenClaw's built-in OpenAI Codex authentication, follow that version's official flow and do not put both credential sets in the same provider.
Related OpenClaw guides
Done
Setup complete. OpenClaw now calls Codex through Lumecoder, with support for streaming and tool calling.