opencodex-gateway

OpenCodex Gateway

Skill by ara.so — Codex Skills collection.

OpenCodex is a zero-config local gateway that enables Codex Desktop to use third-party APIs (OpenAI-compatible endpoints). It features a bilingual web dashboard for model management, a custom Computer Use engine with native macOS control, and Vision Bridge that lets text-only models handle visual tasks by automatically describing screenshots.

Installation

git clone https://github.com/AITabby/opencodex.git
cd opencodex
npm install
npm start

The server starts on http://localhost:8765 and automatically:

Patches ~/.codex/config.toml (creates backup)
Opens the dashboard in your browser
Enables the API gateway

Architecture

OpenCodex sits between Codex Desktop and third-party APIs:

Codex Desktop → OpenCodex Gateway (localhost:8765) → Third-party API
                      ↓
                Vision Bridge (optional)
                Computer Use Engine

Web Dashboard

Access at http://localhost:8765/dashboard

Key Features

API Configuration: Set base URL, API key, model names
Model Management: Add/remove models, toggle visibility in Codex
Language Toggle: Switch between English and Chinese
Live Logs: SSE-streamed request/response logs
One-Click Actions: Restart Codex, reset to native config

Configuration Flow

Open dashboard
Enter API endpoint (e.g., https://api.openai.com/v1 or https://api.deepseek.com)
Add API key (stored in ~/.codex/config.toml)
Add model names (e.g., gpt-4, deepseek-chat)
Check boxes for models you want visible in Codex
Click "Save Configuration"

Configuration Files

Auto-Generated Config

OpenCodex modifies ~/.codex/config.toml:

[api]
base_url = "http://localhost:8765/v1"
api_key = "your-actual-api-key"

[[models]]
name = "gpt-4"
enabled = true

[[models]]
name = "deepseek-chat"
enabled = true

Original config backed up to ~/.codex/config.toml.backup

Environment Variables

For development or custom deployments:

export OPENCODEX_PORT=8765
export OPENCODEX_API_KEY=sk-your-key-here
export OPENCODEX_BASE_URL=https://api.openai.com/v1

Vision Bridge

Vision Bridge enables text-only models to handle Computer Use tasks by converting screenshots to text descriptions.

How It Works

Codex sends Computer Use request with screenshot
OpenCodex detects text-only model
Screenshot compressed to 1200px with sips
Vision model describes the screenshot
Description injected into the prompt
Text-only model receives modified request

Configuration

In the dashboard, configure Vision Bridge settings:

{
  "vision_bridge": {
    "enabled": true,
    "endpoint": "https://api.openai.com/v1",
    "model": "gpt-4-vision-preview",
    "api_key": "process.env.VISION_API_KEY",
    "max_dimension": 1200
  }
}

Programmatic Example

If extending OpenCodex, here's how Vision Bridge is invoked:

import { VisionBridge } from './vision-bridge';

const bridge = new VisionBridge({
  endpoint: process.env.VISION_ENDPOINT,
  model: 'gpt-4-vision-preview',
  apiKey: process.env.VISION_API_KEY
});

// Automatically converts screenshot to description
const description = await bridge.describeImage(screenshotBase64);
// Injects into prompt for text-only model
const modifiedPrompt = bridge.injectDescription(originalPrompt, description);

Computer Use Engine

OpenCodex implements custom Computer Use actions for macOS using native CGEvent APIs.

Supported Actions

Mouse: Click, move, drag, scroll
Keyboard: Type text, press keys, shortcuts
Window: Focus, resize, minimize
Screenshot: Capture and compress

Action Format

Codex sends tool calls in this format:

{
  "type": "computer_use",
  "action": "mouse_click",
  "params": {
    "x": 500,
    "y": 300,
    "button": "left"
  }
}

Example Actions

Mouse Click

{
  "action": "mouse_click",
  "params": { "x": 500, "y": 300, "button": "left" }
}

Type Text

{
  "action": "type_text",
  "params": { "text": "Hello, world!" }
}

Screenshot

{
  "action": "screenshot",
  "params": { "max_dimension": 1200 }
}

Response includes base64 image:

{
  "success": true,
  "image": "iVBORw0KGgoAAAANS..."
}

API Reference

Proxy Endpoint

All OpenAI-compatible requests go through:

POST http://localhost:8765/v1/chat/completions

Headers:

Authorization: Bearer <your-api-key>
Content-Type: application/json

Dashboard API

Get Configuration

curl http://localhost:8765/api/config

Update Configuration

curl -X POST http://localhost:8765/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "base_url": "https://api.deepseek.com",
    "api_key": "sk-...",
    "models": [
      {"name": "deepseek-chat", "enabled": true}
    ]
  }'

Restart Codex

curl -X POST http://localhost:8765/api/restart-codex

Reset to Native

curl -X POST http://localhost:8765/api/reset-native

Live Logs (SSE)

curl -N http://localhost:8765/api/logs

Stream format:

data: {"timestamp": "2026-06-04T10:30:00Z", "level": "info", "message": "Request to gpt-4"}

data: {"timestamp": "2026-06-04T10:30:01Z", "level": "info", "message": "Response 200"}

Common Patterns

Adding Multiple Models

const models = [
  { name: 'gpt-4-turbo', enabled: true },
  { name: 'gpt-4', enabled: true },
  { name: 'claude-3-opus', enabled: false }
];

await fetch('http://localhost:8765/api/config', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ models })
});

Switching Providers

To switch from OpenAI to DeepSeek:

Open dashboard
Change base URL to https://api.deepseek.com
Update API key
Change model name to deepseek-chat
Enable Vision Bridge (DeepSeek is text-only)
Save configuration

Custom Vision Model

Use a different vision model for Vision Bridge:

{
  "vision_bridge": {
    "enabled": true,
    "endpoint": "https://api.anthropic.com/v1",
    "model": "claude-3-opus-20240229",
    "api_key": "process.env.ANTHROPIC_API_KEY"
  }
}

Troubleshooting

Codex Not Connecting

Symptom: Codex shows "API Error" or "Connection Failed"

Solution:

Verify OpenCodex is running: curl http://localhost:8765/health
Check ~/.codex/config.toml has base_url = "http://localhost:8765/v1"
Restart Codex via dashboard or manually
Check logs: http://localhost:8765/dashboard → scroll to logs

Models Not Appearing

Symptom: Added models don't show in Codex

Solution:

Ensure model checkbox is checked in dashboard
Click "Save Configuration"
Restart Codex (one-click button in dashboard)
Verify ~/.codex/config.toml includes the model with enabled = true

Vision Bridge Not Working

Symptom: Text-only model fails on Computer Use tasks

Solution:

Enable Vision Bridge in dashboard
Configure vision model endpoint and API key
Test vision model separately: curl -X POST <vision_endpoint>/chat/completions
Check OpenCodex logs for vision errors
Ensure screenshot compression succeeds: verify sips is available (which sips)

Rate Limiting

Symptom: 429 errors in logs

Solution:

OpenCodex passes through rate limits from upstream API
Reduce request frequency in Codex
Check API provider's rate limits
Consider adding retry logic (upstream API responsibility)

Port Already in Use

Symptom: Error: listen EADDRINUSE: address already in use :::8765

Solution:

# Find process on port 8765
lsof -i :8765
# Kill it
kill -9 <PID>
# Or change port
export OPENCODEX_PORT=8766
npm start

Config Corruption

Symptom: Codex behaves unexpectedly after config changes

Solution:

Click "Reset to Native Codex" in dashboard
Restores ~/.codex/config.toml.backup
Restart Codex
Reconfigure OpenCodex carefully

Screenshot Too Large

Symptom: Vision API rejects screenshots

Solution:

Default max dimension: 1200px
Reduce in Vision Bridge settings:

{ "max_dimension": 800 }

Verify compression: check OpenCodex logs for sips output

Development

Project Structure

opencodex/
├── src/
│   ├── server.ts          # Main Express server
│   ├── vision-bridge.ts   # Vision Bridge logic
│   ├── computer-use.ts    # macOS automation
│   └── config.ts          # Config patching
├── public/
│   └── dashboard.html     # Web UI
└── package.json

Running in Dev Mode

npm run dev  # Enables hot-reload

Adding Custom Actions

Extend Computer Use engine:

// src/computer-use.ts
export async function customAction(params: any) {
  // Use node-mac-automation or applescript
  const result = execSync(`osascript -e 'tell application "Finder" to ...'`);
  return { success: true, result: result.toString() };
}

case 'custom_action':
  return await customAction(params);

Logging

Add custom logs visible in dashboard:

import { logger } from './logger';

logger.info('Custom event', { data: someData });
logger.error('Something failed', { error });

Integration with OpenCodexBar

For the ultimate experience, pair with OpenCodexBar:

Run OpenCodex gateway: npm start
Clone and compile OpenCodexBar
Launch bar app
Press Option + Space for system-wide voice activation
Enjoy real-time audio VAD and cinematic visualizer

Both projects work independently but are designed to complement each other.

About this skill

Installation

Architecture

Web Dashboard

Key Features

Configuration Flow

Configuration Files

Auto-Generated Config

Environment Variables

Vision Bridge

How It Works

Configuration

Programmatic Example

Computer Use Engine

Supported Actions

Action Format

Example Actions

Mouse Click

Type Text

Screenshot

API Reference

Proxy Endpoint

Dashboard API

Get Configuration

Update Configuration

Restart Codex

Reset to Native

Live Logs (SSE)

Common Patterns

Adding Multiple Models

Switching Providers

Custom Vision Model

Troubleshooting

Codex Not Connecting

Models Not Appearing

Vision Bridge Not Working

Rate Limiting

Port Already in Use

Config Corruption

Screenshot Too Large

Development

Project Structure

Running in Dev Mode

Adding Custom Actions

Logging

Integration with OpenCodexBar