| 1 | # Codex |
| 2 | |
| 3 | [Codex](https://github.com/openai/codex) is OpenAI's official agentic coding tool that lives in your terminal. It can understand your codebase, edit files, run commands, and help you write code more efficiently. |
| 4 | |
| 5 | By pointing Codex at a vLLM server, you can use your own models as the backend instead of the OpenAI API. This is useful for: |
| 6 | |
| 7 | - Running fully local/private coding assistance |
| 8 | - Using open-weight models with tool calling capabilities |
| 9 | - Testing and developing with custom models |
| 10 | |
| 11 | ## How It Works |
| 12 | |
| 13 | vLLM implements the OpenAI-Responses API, which is the same API that Codex uses to communicate with OpenAI's servers. By configuring Codex to point at your vLLM server, Codex sends its requests to vLLM instead of OpenAI. vLLM then translates these requests to work with your local model and returns responses in the format Codex expects. |
| 14 | |
| 15 | This means any model served by vLLM with proper tool calling support can act as a drop-in replacement for OpenAI models in Codex. |
| 16 | |
| 17 | ## Requirements |
| 18 | |
| 19 | Codex requires a model with strong tool calling capabilities. The model must support the OpenAI-Responses tool calling API. See [Tool Calling](../../features/tool_calling.md) for details on enabling tool calling for your model. |
| 20 | |
| 21 | ## Installation |
| 22 | |
| 23 | First, install Codex by following the [official installation guide](https://github.com/openai/codex). |
| 24 | |
| 25 | ## Starting the vLLM Server |
| 26 | |
| 27 | Start vLLM with a tool-calling capable model - here's an example using `Qwen/Qwen3-27B`: |
| 28 | |
| 29 | ```bash |
| 30 | vllm serve Qwen/Qwen3.6-27B --port 8000 --tensor-parallel-size 8 --max-model-len 262144 --reasoning-parser qwen3 --enable-auto-tool-choice --tool-call-parser qwen3_coder |
| 31 | |
| 32 | ``` |
| 33 | |
| 34 | For other models, you'll need to enable tool calling explicitly with `--enable-auto-tool-choice` and the right `--tool-call-parser`. Refer to the [Tool Calling documentation](../../features/tool_calling.md) for the correct flags for your model. |
| 35 | |
| 36 | ## Configuring Codex |
| 37 | |
| 38 | Codex is configured via a TOML file located at `~/.codex/config.toml`. Create or edit this file to point Codex at your vLLM server: |
| 39 | |
| 40 | ```toml |
| 41 | model = "my-model" |
| 42 | model_provider = "vllm" |
| 43 | |
| 44 | [model_providers.vllm] |
| 45 | name = "vLLM" |
| 46 | env_key = "VLLM_API_KEY" |
| 47 | base_url = "http://localhost:8000/v1" |
| 48 | wire_api = "responses" |
| 49 | ``` |
| 50 | |
| 51 | The configuration fields: |
| 52 | |
| 53 | | Field | Description | |
| 54 | | ----- | ----------- | |
| 55 | | `model` | The model name to use. Must match the `--served-model-name` you passed to vLLM. | |
| 56 | | `model_provider` | Set to `"vllm"` to use your local vLLM server. | |
| 57 | | `[model_providers.vllm]` | Configuration section for the vLLM provider. | |
| 58 | | `name` | A display name for your vLLM provider. | |
| 59 | | `env_key` | The name of an environment variable that Codex will read for the API key. vLLM does not require authentication by default, so this can be any value. | |
| 60 | | `base_url` | The URL of your vLLM server's OpenAI-compatible API endpoint (default is `http://localhost:8000/v1`). | |
| 61 | | `wire_api` | The API style to use. Set to `"responses"` for the OpenAI Responses API | |
| 62 | |
| 63 | !!! tip |
| 64 | You can set the `env_key` to any dummy environment variable since vLLM doesn't require authentication by default: |
| 65 | ```bash |
| 66 | export VLLM_API_KEY=dummy |
| 67 | ``` |
| 68 | |
| 69 | !!! warning |
| 70 | When using the `responses` API, ensure your vLLM version supports the OpenAI Responses API. |
| 71 | |
| 72 | ## Testing the Setup |
| 73 | |
| 74 | Once Codex is configured, launch it in your project directory: |
| 75 | |
| 76 | ```bash |
| 77 | codex |
| 78 | ``` |
| 79 | |
| 80 | Try a simple prompt to verify the connection, such as asking it to explain a file in your project. If the model responds correctly, your setup is working. You can now use Codex with your vLLM-served model for coding tasks. |
| 81 | |
| 82 | ## Troubleshooting |
| 83 | |
| 84 | **Connection refused**: Ensure vLLM is running and accessible at the specified URL. Check that the port matches and that `base_url` includes the `/v1` path suffix. |
| 85 | |
| 86 | **Tool calls not working**: Verify that your model supports tool calling and that you've enabled it with the correct `--tool-call-parser` flag. See [Tool Calling](../../features/tool_calling.md). |
| 87 | |
| 88 | **Model not found**: Ensure the `model` field in `~/.codex/config.toml` matches the `--served-model-name` you passed to vLLM. |