|
| 1 | +# Using DFlash with OpenAI Codex CLI |
| 2 | + |
| 3 | +This guide covers installing Codex CLI, configuring it to use the local |
| 4 | +DFlash server, and common usage patterns. |
| 5 | + |
| 6 | +## Prerequisites |
| 7 | + |
| 8 | +- **DFlash server** built and model files downloaded (see [DEVELOPER.md](DEVELOPER.md)) |
| 9 | +- **Node.js ≥ 18** |
| 10 | + |
| 11 | +## 1. Install Codex CLI |
| 12 | + |
| 13 | +```bash |
| 14 | +npm install -g @openai/codex |
| 15 | +codex --version # should print 0.1xx.x |
| 16 | +``` |
| 17 | + |
| 18 | +> If you get a permission error, use a user-level prefix: |
| 19 | +> ```bash |
| 20 | +> mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global |
| 21 | +> export PATH=~/.npm-global/bin:$PATH # add to ~/.bashrc |
| 22 | +> npm install -g @openai/codex |
| 23 | +> ``` |
| 24 | +
|
| 25 | +## 2. Start the DFlash Server |
| 26 | +
|
| 27 | +```bash |
| 28 | +cd dflash |
| 29 | +python scripts/server.py \ |
| 30 | + --draft models/draft/draft-Qwen3.6-27B.gguf \ |
| 31 | + --port 8080 |
| 32 | +``` |
| 33 | +
|
| 34 | +Wait until you see: |
| 35 | + |
| 36 | +``` |
| 37 | +INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) |
| 38 | +``` |
| 39 | + |
| 40 | +### Quick smoke test |
| 41 | + |
| 42 | +```bash |
| 43 | +curl -s http://localhost:8080/v1/responses \ |
| 44 | + -H "Content-Type: application/json" \ |
| 45 | + -d '{"model":"luce-dflash","input":"Say hi","max_output_tokens":32}' \ |
| 46 | + | python3 -m json.tool |
| 47 | +``` |
| 48 | + |
| 49 | +## 3. Configure Codex |
| 50 | + |
| 51 | +Create or edit `~/.codex/config.toml`: |
| 52 | + |
| 53 | +```toml |
| 54 | +model = "luce-dflash" |
| 55 | +model_provider = "dflash" |
| 56 | + |
| 57 | +[model_providers.dflash] |
| 58 | +name = "DFlash" |
| 59 | +base_url = "http://localhost:8080/v1" |
| 60 | +wire_api = "responses" |
| 61 | +supports_websockets = false |
| 62 | +``` |
| 63 | + |
| 64 | +Key points: |
| 65 | + |
| 66 | +| Field | Why | |
| 67 | +|---|---| |
| 68 | +| `name` | **Required** — Codex rejects providers with an empty name | |
| 69 | +| `wire_api = "responses"` | Codex only supports the Responses API | |
| 70 | +| `supports_websockets = false` | DFlash serves HTTP only | |
| 71 | +| No `env_key` | Local server needs no auth token | |
| 72 | + |
| 73 | +## 4. Using Codex |
| 74 | + |
| 75 | +### Interactive mode |
| 76 | + |
| 77 | +```bash |
| 78 | +codex # opens the TUI |
| 79 | +``` |
| 80 | + |
| 81 | +### Non-interactive (exec) |
| 82 | + |
| 83 | +```bash |
| 84 | +# Simple question |
| 85 | +codex exec "What is 2+2?" |
| 86 | + |
| 87 | +# Coding task in a repo |
| 88 | +cd /path/to/your/project |
| 89 | +codex exec "Add input validation to the login handler" |
| 90 | + |
| 91 | +# Code review |
| 92 | +codex exec review |
| 93 | +``` |
| 94 | + |
| 95 | +### Approval policies |
| 96 | + |
| 97 | +```bash |
| 98 | +codex --approval-policy suggest ... # suggest commands, ask before running |
| 99 | +codex --approval-policy auto-edit ... # auto-approve file edits, ask for shell |
| 100 | +codex --approval-policy full-auto ... # auto-approve everything |
| 101 | +``` |
| 102 | + |
| 103 | +### Reasoning effort |
| 104 | + |
| 105 | +The server maps reasoning effort to Qwen's thinking mode: |
| 106 | + |
| 107 | +- `low` (default) — thinking disabled, fastest responses |
| 108 | +- `medium` / `high` — thinking enabled (`<think>` tags) |
| 109 | + |
| 110 | +```bash |
| 111 | +codex -c 'model_reasoning_effort="medium"' exec "Refactor this module" |
| 112 | +``` |
| 113 | + |
| 114 | +## 5. Troubleshooting |
| 115 | + |
| 116 | +### "provider name must not be empty" |
| 117 | + |
| 118 | +Add `name = "DFlash"` (or any non-empty string) to `[model_providers.dflash]`. |
| 119 | + |
| 120 | +### "Reconnecting… 1/5" loop |
| 121 | + |
| 122 | +The server is returning an error. Check: |
| 123 | + |
| 124 | +1. **Server is running** — `curl http://localhost:8080/health` |
| 125 | +2. **Port matches config** — `base_url` must match `--port` |
| 126 | +3. **Server logs** — look at the terminal where `server.py` is running |
| 127 | + |
| 128 | +Common causes: |
| 129 | + |
| 130 | +- Server not started yet (daemon still loading model) |
| 131 | +- Port mismatch between config and server |
| 132 | +- Proxy intercepting localhost (set `no_proxy=localhost`) |
| 133 | + |
| 134 | +### "Unknown model luce-dflash" |
| 135 | + |
| 136 | +This warning is normal — Codex doesn't recognize custom model names but |
| 137 | +uses fallback metadata. It does not affect functionality. |
| 138 | + |
| 139 | +### Slow first response |
| 140 | + |
| 141 | +The first request triggers model loading into GPU memory. Subsequent |
| 142 | +requests reuse the loaded model and are much faster. |
| 143 | + |
| 144 | +## 6. Server CLI Reference |
| 145 | + |
| 146 | +``` |
| 147 | +python scripts/server.py [OPTIONS] |
| 148 | +
|
| 149 | +Options: |
| 150 | + --host HOST Bind address (default: 0.0.0.0) |
| 151 | + --port PORT Bind port (default: 8080) |
| 152 | + --target PATH Target model GGUF (default: models/Qwen3.6-27B-Q4_K_M.gguf) |
| 153 | + --draft PATH Draft model for speculative decoding |
| 154 | + --budget N Speculation budget (default: 22) |
| 155 | + --max-ctx N Max context length (default: model-dependent) |
| 156 | + --tokenizer NAME HuggingFace tokenizer (auto-detected from model) |
| 157 | +``` |
0 commit comments