openclaude-multi-llm

# OpenClaude Multi-LLM Skill

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

OpenClaude is a fork of Claude Code that routes all LLM calls through an OpenAI-compatible shim (`openaiShim.ts`), letting you use any model that speaks the OpenAI Chat Completions API — GPT-4o, DeepSeek, Gemini via OpenRouter, Ollama, Groq, Mistral, Azure, and more — while keeping every Claude Code tool intact (Bash, FileRead, FileWrite, FileEdit, Glob, Grep, WebFetch, Agent, MCP, Tasks, LSP, NotebookEdit).

---

## Installation

### npm (recommended)

```bash
npm install -g @gitlawb/openclaude
# CLI command installed: openclaude
```

### From source (requires Bun)

```bash
git clone https://node.gitlawb.com/z6MkqDnb7Siv3Cwj7pGJq4T5EsUisECqR8KpnDLwcaZq5TPr/openclaude.git
cd openclaude
bun install
bun run build
# optionally link globally
npm link
```

### Run without build

```bash
bun run dev       # run directly with Bun, no build step
```

---

## Activation — Required Environment Variables

You must set `CLAUDE_CODE_USE_OPENAI=1` to enable the shim. Without it, the tool falls back to the Anthropic SDK.

| Variable | Required | Purpose |
|---|---|---|
| `CLAUDE_CODE_USE_OPENAI` | Yes | Set to `1` to activate OpenAI provider |
| `OPENAI_API_KEY` | Yes* | API key (*omit for local Ollama/LM Studio) |
| `OPENAI_MODEL` | Yes | Model identifier |
| `OPENAI_BASE_URL` | No | Custom endpoint (default: `https://api.openai.com/v1`) |
| `CODEX_API_KEY` | Codex only | ChatGPT/Codex access token |
| `CODEX_AUTH_JSON_PATH` | Codex only | Path to Codex CLI `auth.json` |

`OPENAI_MODEL` takes priority over `ANTHROPIC_MODEL` if both are set.

---

## Provider Configuration Examples

### OpenAI

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=$OPENAI_API_KEY
export OPENAI_MODEL=gpt-4o
openclaude
```

### DeepSeek

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=$DEEPSEEK_API_KEY
export OPENAI_BASE_URL=https://api.deepseek.com/v1
export OPENAI_MODEL=deepseek-chat
openclaude
```

### Google Gemini (via OpenRouter)

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=$OPENROUTER_API_KEY
export OPENAI_BASE_URL=https://openrouter.ai/api/v1
export OPENAI_MODEL=google/gemini-2.0-flash
openclaude
```

### Ollama (local, no API key needed)

```bash
ollama pull llama3.3:70b

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=llama3.3:70b
openclaude
```

### Groq

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=$GROQ_API_KEY
export OPENAI_BASE_URL=https://api.groq.com/openai/v1
export OPENAI_MODEL=llama-3.3-70b-versatile
openclaude
```

### Mistral

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=$MISTRAL_API_KEY
export OPENAI_BASE_URL=https://api.mistral.ai/v1
export OPENAI_MODEL=mistral-large-latest
openclaude
```

### Azure OpenAI

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=$AZURE_OPENAI_KEY
export OPENAI_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment/v1
export OPENAI_MODEL=gpt-4o
openclaude
```

### Codex (ChatGPT backend)

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_MODEL=codexplan   # or codexspark for faster loops
# reads ~/.codex/auth.json automatically if present
# or set: export CODEX_API_KEY=$CODEX_TOKEN
openclaude
```

### LM Studio (local)

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:1234/v1
export OPENAI_MODEL=your-model-name
openclaude
```

### Together AI

```bash
export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=$TOGETHER_API_KEY
export OPENAI_BASE_URL=https://api.together.xyz/v1
export OPENAI_MODEL=meta-llama/Llama-3.3-70B-Instruct-Turbo
openclaude
```

---

## Architecture — How the Shim Works

The shim file is `src/services/api/openaiShim.ts` (724 lines). It duck-types the Anthropic SDK interface so the rest of Claude Code is unaware it's talking to a different provider.

```
Claude Code Tool System
        │
        ▼
Anthropic SDK interface (duck-typed)
        │
        ▼
openaiShim.ts  ← format translation layer
        │
        ▼
OpenAI Chat Completions API
        │
        ▼
Any compatible model
```

### What the shim translates

- Anthropic message content blocks → OpenAI `messages` array
- Anthropic `tool_use` / `tool_result` blocks → OpenAI `function_calls` / `tool` messages
- OpenAI SSE streaming chunks → Anthropic stream events
- Anthropic system prompt arrays → OpenAI `system` role messages

### Files changed from upstream

```
src/services/api/openaiShim.ts   ← NEW: the shim (724 lines)
src/services/api/client.ts       ← routes to shim when CLAUDE_CODE_USE_OPENAI=1
src/utils/model/providers.ts     ← added 'openai' provider type
src/utils/model/configs.ts       ← added openai model mappings
src/utils/model/model.ts         ← respects OPENAI_MODEL for defaults
src/utils/auth.ts                ← recognizes OpenAI as valid 3rd-party provider
```

---

## Developer Workflow — Key Commands

```bash
# Run in dev mode (no build)
bun run dev

# Build distribution
bun run build

# Launch with persisted profile (.openclaude-profile.json)
bun run dev:profile

# Launch with OpenAI profile (requires OPENAI_API_KEY in shell)
bun run dev:openai

# Launch with Ollama profile (localhost:11434, llama3.1:8b default)
bun run dev:ollama

# Launch with Codex profile
bun run dev:codex

# Quick startup sanity check
bun run smoke

# Validate provider env + reachability
bun run doctor:runtime

# Machine-readable runtime diagnostics
bun run doctor:runtime:json

# Persist diagnostics report to reports/doctor-runtime.json
bun run doctor:report

# Full local hardening check (typecheck + smoke + runtime doctor)
bun run hardening:check

# Strict hardening (includes project-wide typecheck)
bun run hardening:strict
```

---

## Profile Bootstrap — One-Time Setup

Profiles save provider config to `.openclaude-profile.json` so you don't repeat env exports.

```bash
# Auto-detect provider (ollama if running, otherwise openai)
bun run profile:init

# Bootstrap for OpenAI
bun run profile:init -- --provider openai --api-key $OPENAI_API_KEY

# Bootstrap for Ollama with custom model
bun run profile:init -- --provider ollama --model llama3.1:8b

# Bootstrap for Codex
bun run profile:init -- --provider codex --model codexspark
bun run profile:codex
```

After bootstrapping, run the app via the persisted profile:

```bash
bun run dev:profile
```

---

## TypeScript Integration — Using the Shim Directly

If you want to use the shim in your own TypeScript code:

```typescript
// src/services/api/client.ts pattern — routing to the shim
import { openaiShim } from './openaiShim.js';

const useOpenAI = process.env.CLAUDE_CODE_USE_OPENAI === '1';

const client = useOpenAI
  ? openaiShim({
      apiKey: process.env.OPENAI_API_KEY,
      baseURL: process.env.OPENAI_BASE_URL ?? 'https://api.openai.com/v1',
      model: process.env.OPENAI_MODEL ?? 'gpt-4o',
    })
  : new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
```

```typescript
// Streaming usage pattern (mirrors Anthropic SDK interface)
const stream = await client.messages.stream({
  model: process.env.OPENAI_MODEL!,
  max_tokens: 32000,
  system: 'You are a helpful coding assistant.',
  messages: [
    { role: 'user', content: 'Refactor this function for readability.' }
  ],
  tools: myTools, // Anthropic-format tool definitions — shim translates them
});

for await (const event of stream) {
  // events arrive in Anthropic format regardless of underlying provider
  if (event.type === 'content_block_delta') {
    process.stdout.write(event.delta.text ?? '');
  }
}
```

---

## Model Quality Reference

| Model | Tool Calling | Code Quality | Speed |
|---|---|---|---|
| GPT-4o | Excellent | Excellent | Fast |
| DeepSeek-V3 | Great | Great | Fast |
| Gemini 2.0 Flash | Great | Good | Very Fast |
| Llama 3.3 70B | Good | Good | Medium |
| Mistral Large | Good | Good | Fast |
| GPT-4o-mini | Good | Good | Very Fast |
| Qwen 2.5 72B | Good | Good | Medium |
| Models < 7B | Limited | Limited | Very Fast |

For agentic multi-step tool use, prefer models with strong native function/tool calling (GPT-4o, DeepSeek-V3, Gemini 2.0 Flash).

---

## What Works vs. What Doesn't

### Fully supported
- All tools: Bash, FileRead, FileWrite, FileEdit, Glob, Grep, WebFetch, WebSearch, Agent, MCP, LSP, NotebookEdit, Tasks
- Streaming (real-time token output)
- Multi-step tool chains
- Vision/images (base64 and URL) for models that support them
- Slash commands: `/commit`, `/review`, `/compact`, `/diff`, `/doctor`
- Sub-agents (AgentTool spawns sub-agents using the same provider)
- Persistent memory

### Not supported (Anthropic-specific features)
- Extended thinking / reasoning mode
- Prompt caching (Anthropic cache headers skipped)
- Anthropic beta feature headers
- Token output defaults to 32K max (gracefully capped if model is lower)

---

## Troubleshooting

### `doctor:runtime` fails with placeholder key error

```
Error: OPENAI_API_KEY looks like a placeholder (SUA_CHAVE)
```

Set a real key: `export OPENAI_API_KEY=$YOUR_ACTUAL_KEY`

### Ollama connection refused

Ensure Ollama is running before launching:

```bash
ollama serve &
ollama pull llama3.3:70b
bun run dev:ollama
```

### Tool calls not working / model ignores tools

Switch to a model with strong tool calling support (GPT-4o, DeepSeek-V3). Models under 7B parameters often fail at multi-step agentic tool use.

### Azure endpoint format

The `OPENAI_BASE_URL` for Azure must include the deployment path:

```
https://<resource>.openai.azure.com/openai/deployments/<deployment>/v1
```

### Codex auth not found

If `~/.codex/auth.json` doesn't exist, set the token directly:

```bash
export CODEX_API_KEY=$YOUR_CODEX_TOKEN
```

Or point to a custom auth file:

```bash
export CODEX_AUTH_JSON_PATH=/path/to/auth.json
```

### Run diagnostics for any issue

```bash
bun run doctor:runtime       # human-readable
bun run doctor:runtime:json  # machine-readable JSON
bun run doctor:report        # saves to reports/doctor-runtime.json
```