Connecting external models to Codex is a complex process. This guide uses the Kimi API as a hands-on example to walk you through the complete Codex API configuration on macOS and Windows.
What is Codex?
Codex is OpenAI's coding agent for repository and terminal work. It can:
Write code: Create functions, tests, scripts, and focused features.
Understand unfamiliar codebases: Search files, trace calls, and explain components.
Review code: Identify likely defects, risky assumptions, missing tests, and security concerns.
Debug and fix problems: Reproduce errors, propose changes, and run checks.
Automate routine work: Update files and execute documented workflows with your approval.
Install and sign in to Codex
Part 1: Install Codex CLI
Open Terminal on macOS or PowerShell on Windows.
Run the command for your operating system:
macOS:
curl -fsSL https://chatgpt.com/codex/install.sh | shWindows:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"Wait for the installation to finish, then close and reopen Terminal or PowerShell.
Run:
codexSelect Sign in with ChatGPT, complete the browser sign-in, and return to Terminal or PowerShell.
Part 2: Install the Codex desktop app
Visit the official Codex desktop app page.
Download the ChatGPT desktop app for macOS or Windows.
Install and open the app, then sign in with your ChatGPT account.
Create a task or open a project and select Codex as the work mode.
Enter
Say hello in one sentence.and send the message.
Built-in AI models vs. external LLM APIs
After installing Codex, you can use its built-in AI models or connect a compatible external LLM API. The best option depends on how much setup, flexibility, and account management you want.
Use Codex built-in models
Built-in models provide the simplest experience. You can select an available model and begin coding without running another service or configuring a separate API key.
Advantages:
Quick setup with no additional configuration steps.
Direct integration with Codex tools and features
Fewer services and credentials to manage
Limitations:
You can only choose from the models available to your account
Less flexibility if you want to use a model from another provider
Requires a GPT subscription, and the usage cost is relatively high.
Use an external LLM API
An external API gives you more model choices and lets you use an existing account with another provider. However, some models require additional configuration or a local compatibility tool before Codex can use them.
Advantages:
Access to models from other providers
More flexibility for different coding tasks
Separate control over the external API account and usage
No GPT subscription required. Ideal for cost-sensitive scenarios.
Limitations:
Requires an API key and additional configuration
May require a local router that must remain running
Billing, compatibility, privacy, and troubleshooting depend on the external provider
If you want the fastest setup, start with a built-in model. If you already have an external API account or want more model choices, continue with the following walkthrough. It uses Kimi API as a practical example of connecting an external model to Codex.
How to Connect an External LLM API to Codex: Kimi Example
macOS setup
Step 1: Open Terminal A and verify Node.js and npm
Where: Press Command+Space, type Terminal, and press Enter. Treat this first window as Terminal A.
Run:
node --version
npm --versionExpected result: Each command prints a version. Outputs such as v22.x.x for Node.js and 10.x.x for npm are examples only, not minimum requirements.
If a command is not found: Open a browser, visit https://nodejs.org/en/download, download the LTS macOS .pkg, open Downloads in Finder, double-click the package, and accept the installer defaults. Close Terminal with Command+Q, reopen Terminal A, and run both version commands again. Do not continue until both commands return versions.
Step 2: Create a Kimi API key
Open the Kimi API platform. Create an API key from the console, then store it in a password manager or secret manager. If your console only shows the full key once, copy it before leaving the page.
Step 3: Set MOONSHOT_API_KEY in Terminal A
Where: Return to Terminal A.
Run:
export MOONSHOT_API_KEY="YOUR_KIMI_API_KEY"Replace only YOUR_KIMI_API_KEY with the real Kimi key. Keep the quotation marks and the variable name MOONSHOT_API_KEY unchanged.
Expected result: The export command prints no output. Verify that a value exists without displaying it:
test -n "$MOONSHOT_API_KEY" && echo "Kimi key is set"Terminal should print Kimi key is set.
Step 4: Test Kimi directly from Terminal A
Where: Keep using Terminal A, where MOONSHOT_API_KEY is set.
Run:
curl --silent --show-error https://api.moonshot.ai/v1/chat/completions \
-H "Authorization: Bearer $MOONSHOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"kimi-k2.7-code","messages":[{"role":"user","content":"Say hello in one sentence."}],"stream":false}'Expected result: A JSON response appears and contains generated text under choices[0].message.content.
Step 5: Open Terminal B and start the router in Terminal A
Where: With Terminal A active, press Command+N to open a second window. Call the new window Terminal B. Return to Terminal A before running the router command.
Run in Terminal A:
npx @codeproxy/cli --base-url https://api.moonshot.ai/v1 --model kimi-k2.7-code --apikey "$MOONSHOT_API_KEY"Do not replace the base URL or model. $MOONSHOT_API_KEY must remain the variable reference, not a second pasted copy of the key.
Possible first-run prompt: npx may display Need to install ... Ok to proceed? (y). Review the package name and the linked third-party source first. Type y and press Enter only if you accept that package. No exact package version is claimed as tested here.
Expected result: The process stays running and reports that it is listening on 127.0.0.1:8787. Leave Terminal A open.
If it fails: If npm cannot download the package, confirm internet access and rerun node --version and npm --version. If port 8787 is already in use, stop the other local process using that port or return to its terminal and press Ctrl+C, then rerun the router command.
Step 6: Test localhost from Terminal B
Where: Click Terminal B.
Run:
curl --no-buffer --show-error http://127.0.0.1:8787/v1/responses \
-H "Content-Type: application/json" \
-d '{"model":"kimi-k2.7-code","input":"Say hello in one sentence.","stream":true}'Expected result: Terminal B prints Responses-like streaming events or output containing a one-sentence greeting. The exact event sequence can vary by router release.
If you see Connection refused: Look at Terminal A. If the router stopped, rerun the Step 5 command and keep it open. If Terminal A shows an upstream 401, reset MOONSHOT_API_KEY there and restart the router.
Step 7: Create and edit the macOS Codex configuration
Where: Keep using Terminal B.
Run:
mkdir -p "$HOME/.codex"
if [ -f "$HOME/.codex/config.toml" ]; then cp "$HOME/.codex/config.toml" "$HOME/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)"; fi
touch "$HOME/.codex/config.toml"
open -e "$HOME/.codex/config.toml"These commands create the user-level configuration file if necessary, back up an existing file, and open ~/.codex/config.toml in TextEdit.
If the file is empty
Paste the following complete configuration:
model = "kimi-k2.7-code"
model_provider = "kimi-proxy"
model_context_window = 256000
model_supports_reasoning_summaries = false
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000If the file already contains settings
Do not paste the complete configuration over the existing file. Keep unrelated settings and update the required lines individually.
Find the line beginning with
model =and replace the entire line with:
model = "kimi-k2.7-code"Find the line beginning with
model_provider =and replace the entire line with:
model_provider = "kimi-proxy"Find the line beginning with
model_context_window =and replace the entire line with:
model_context_window = 256000Find the line beginning with
model_supports_reasoning_summaries =and replace the entire line with:
model_supports_reasoning_summaries = falseIf any of these four settings do not already exist, add the missing line near the top of the file.
Find and delete any entire line beginning with:
model_catalog_json =Also find and delete any entire line beginning with:
service_tier =Add the bellow section:
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000Do not remove other provider sections, such as [model_providers.openai].
Keep unrelated existing settings, including notify, approval, sandbox, project, and interface preferences. Do not copy another user’s notify line because it may contain a computer-specific absolute path.
Press Command+S to save the file, then close TextEdit.
Step 8: Restart Codex and run the complete macOS test
Where: Keep the router running in Terminal A. In Terminal B, close any existing Codex session with Ctrl+C, then prepare a disposable folder.
Run in Terminal B:
mkdir -p "$HOME/codex-kimi-test"
cd "$HOME/codex-kimi-test"
codexTest: Type hello. and press Enter. A one-sentence reply confirms a basic request path.
Windows setup
Use two independent PowerShell windows. PowerShell A stores the current-session Kimi key and runs the router. PowerShell B tests localhost, edits configuration, and starts Codex. The persistent User variable supports future windows; the current-session assignment makes the key available immediately in PowerShell A.
Step 1: Open PowerShell A and verify Node.js and npm
Where: Press the Windows key, type PowerShell, and open Windows PowerShell. Call this window PowerShell A.
Run:
node --version
npm --versionExpected result: Both commands print versions. Values such as v22.x.x and 10.x.x are examples only, not minimum requirements.
If a command is not recognized: Open a browser and visit https://nodejs.org/en/download. Download the LTS Windows .msi, open Downloads in File Explorer, double-click the installer, accept the defaults, and ensure the installer keeps the option that adds Node.js to PATH. Close every PowerShell window, reopen PowerShell A, and rerun both commands.
Step 2: Create a Kimi API key
Open the Kimi API platform. Create an API key from the console, then store it in a password manager or secret manager. If your console only shows the full key once, copy it before leaving the page.
Step 3: Set persistent and current-session variables in PowerShell A
Where: Return to PowerShell A.
Run:
[Environment]::SetEnvironmentVariable("MOONSHOT_API_KEY", "YOUR_KIMI_API_KEY", "User")
$env:MOONSHOT_API_KEY = "YOUR_KIMI_API_KEY"Replace only YOUR_KIMI_API_KEY in both lines with the same Kimi key. Keep MOONSHOT_API_KEY, User, quotation marks, and punctuation unchanged. The first line stores the value for future processes. The second line makes it available immediately in PowerShell A.
Expected result: Both commands return no output. Verify presence without printing the key:
$null -ne $env:MOONSHOT_API_KEYPowerShell should print True.
If it prints False: Rerun the current-session assignment with straight quotation marks. If the User write was blocked by policy, continue with the current-session value for this walkthrough and ask your administrator how user environment variables should be stored. Revoke any key exposed in logs or shared text.
Step 4: Test Kimi directly from PowerShell A
API references may display POST URL, but never type POST https://... alone into PowerShell. Use Invoke-RestMethod -Method Post as shown here.
Where: Stay in PowerShell A, where $env:MOONSHOT_API_KEY is set.
Run:
$headers = @{ Authorization = "Bearer $env:MOONSHOT_API_KEY" }
$body = @{ model = "kimi-k2.7-code"; messages = @(@{ role = "user"; content = "Say hello in one sentence." }); stream = $false } | ConvertTo-Json -Depth 5
$response = Invoke-RestMethod -Method Post -Uri "https://api.moonshot.ai/v1/chat/completions" -Headers $headers -ContentType "application/json" -Body $body
$response.choices[0].message.contentDo not replace the endpoint, model, or variable name. PowerShell reads the key from $env:MOONSHOT_API_KEY.
Expected result: The final line prints a one-sentence greeting from choices[0].message.content.
If you receive 401: Confirm the key came from the global .ai console, revoke and recreate it if needed, rerun both Step 3 assignments, and retry. If the model is rejected, confirm the ID is exactly kimi-k2.7-code and check model access in the Kimi console.
Step 5: Open PowerShell B and start the router in PowerShell A
Where: Press the Windows key again, type PowerShell, and open a second Windows PowerShell window. Call it PowerShell B. Return to PowerShell A for the router command.
Run in PowerShell A:
npx @codeproxy/cli --base-url https://api.moonshot.ai/v1 --model kimi-k2.7-code --apikey $env:MOONSHOT_API_KEYKeep $env:MOONSHOT_API_KEY unchanged; do not paste the key directly into the command.
Possible first-run prompt: npx may show Need to install ... Ok to proceed? (y). Review the package and third-party source. Type y and press Enter only if you accept it. No exact package version is claimed as tested.
Expected result: The process remains open and reports that it is listening on 127.0.0.1:8787. Keep PowerShell A open.
If it fails: Run node --version and npm --version in PowerShell A. If either fails, repeat Step 1. If port 8787 is occupied, stop the other router with Ctrl+C in its window, then rerun the command.
Step 6: Test localhost from PowerShell B
Where: Click PowerShell B. Do not stop the router in PowerShell A.
Run:
$localBody = @{ model = "kimi-k2.7-code"; input = "Say hello in one sentence."; stream = $false } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8787/v1/responses" -ContentType "application/json" -Body $localBodyDo not replace the localhost URL. It points to the router in PowerShell A.
Expected result: PowerShell returns a Responses-like object or output containing the greeting. Exact fields can vary by router release.
If the connection is refused: Look at PowerShell A and restart the Step 5 command if the router exited. If PowerShell A shows an upstream authentication error, press Ctrl+C, reset $env:MOONSHOT_API_KEY, and restart the router. Do not add a local authorization header for the default @codeproxy/cli quick start.
Step 7: Create and edit the Windows Codex configuration
Where: Keep using PowerShell B. The provider configuration belongs at $HOME\.codex\config.toml, not inside a project folder.
Run:
New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
$configPath = "$HOME\.codex\config.toml"
if (Test-Path $configPath) { Copy-Item $configPath "$configPath.backup-$(Get-Date -Format 'yyyyMMdd-HHmmss')" }
if (-not (Test-Path $configPath)) { New-Item -ItemType File -Path $configPath | Out-Null }
notepad "$HOME\.codex\config.toml"The commands create the user directory, back up an existing config, create the file if absent, and open it in Notepad.
In Notepad: Paste this complete default configuration, removing conflicting duplicate model or provider keys if the file already contains them:
model_provider = "kimi-proxy"
model = "kimi-k2.7-code"
model_context_window = 256000
model_supports_reasoning_summaries = false
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000Do not replace kimi-proxy, the localhost URL, or responses. Press Ctrl+S and close Notepad.
Confirm the filename: Run:
Get-Item "$HOME\.codex\config.toml" | Select-Object FullName, Name, LengthExpected result: Name is exactly config.toml, not config.toml.txt, and Length is greater than zero.
If Notepad added .txt: In Notepad, choose File → Save As, set Save as type to All Files, enter config.toml, and save it in $HOME\.codex. Rerun Get-Item. If Codex ignores the provider, verify you edited the user-level path and remove duplicate TOML keys.
Step 8: Restart Codex and run the complete Windows test
Where: Leave PowerShell A and its router running. Fully close any Codex app or session. Close PowerShell B, reopen it with Windows key → type PowerShell → open Windows PowerShell, and create a disposable folder.
Run in the reopened PowerShell B:
New-Item -ItemType Directory -Force -Path "$HOME\codex-kimi-test" | Out-Null
Set-Location "$HOME\codex-kimi-test"
codexTest: Type hello. and press Enter.A one-sentence reply confirms a basic request path.
Use Kimi in the Codex desktop app
Before continuing, complete Steps 1–7 of the macOS or Windows setup for the local router and config.toml. You do not need to complete the CLI test first, but the router must remain running while you use Kimi in the desktop app.
Step 1: Keep the local router running
Keep Terminal A or PowerShell A open with @codeproxy/cli running on:
http://127.0.0.1:8787Step 2: Confirm the provider configuration
Open the user-level Codex configuration file.
On macOS, run:
open -e "$HOME/.codex/config.toml"On Windows, run:
notepad "$HOME\.codex\config.toml"Confirm that the file contains these top-level settings:
model = "kimi-k2.7-code"
model_provider = "kimi-proxy"
model_context_window = 256000
model_supports_reasoning_summaries = false
[model_providers.kimi-proxy]
name = "Kimi via local proxy"
base_url = "http://127.0.0.1:8787/v1"
wire_api = "responses"
stream_idle_timeout_ms = 600000Step 3: Fully restart the desktop app
On macOS, press Command+Q to quit the desktop app completely. Closing only the window is not enough.
On Windows, close every desktop app window and confirm that the app is no longer running in the system tray.
Reopen the desktop app and open a project folder.
Step 4: Keep the Custom model selected
The desktop model picker may display Custom instead of Kimi K2.7 Code. This is expected.
Custom providers defined in config.toml are not always displayed by name in the desktop model list. Do not select an OpenAI model such as GPT-5.6 Sol when you want to use the Kimi provider. Keep Custom selected.
You may also see this warning:
Model metadata for `kimi-k2.7-code` not found.
Defaulting to fallback metadata.This is a warning, not a connection failure. The following settings already provide the important model information required for normal use:
model_context_window = 256000
model_supports_reasoning_summaries = falseStep 5: Verify the desktop request path
Send this prompt in the desktop app:
Watch Terminal A or PowerShell A while the desktop app responds. If the Terminal A window receives a new request and the desktop app returns an answer, the desktop app is using the local Kimi route.
Troubleshooting common integration errors
zsh: command not found: POST
POST URL is API-documentation notation, not a command. On macOS, copy the complete curl example. On Windows, copy the complete Invoke-RestMethod -Method Post example.
Connection refused on port 8787
Return to Terminal A or PowerShell A. If no router process is running, set the current-session Kimi variable and rerun the documented npx @codeproxy/cli ... command. Keep that window open, then repeat the localhost test in window B.
A 401 response
Read the router window to identify the failing hop. An upstream Kimi 401 usually means MOONSHOT_API_KEY is invalid, revoked, or from the wrong regional account. Revoke the key in the global .ai console, create a new one, reset the current-session variable, and restart the router. The default router path has no inbound bearer check. A local 401 with another adapter can mean its optional CODEX_KIMI_PROXY_KEY is missing or invalid.
Unsupported parameter or tool errors
The router may be forwarding a field Kimi does not accept. Sampling fields should remain unset; if emitted, they must use the accepted fixed values. Confirm tool_choice is auto or none and that the adapter preserves reasoning_content. If the multi-step test still fails, stop using that router release and choose or update one with explicit Kimi support.
Codex ignores the provider
Open the user file directly: run open -e "$HOME/.codex/config.toml" on macOS or notepad "$HOME\.codex\config.toml" on Windows. Confirm there is one top-level model_provider = "kimi-proxy", one provider table, the localhost base URL, and wire_api = "responses". Save, fully exit Codex, and start it again. Do not put provider selection only in a project .codex/config.toml.
npx cannot start the router
Run node --version and npm --version in router window A. If either command fails, install the Node.js LTS package from nodejs.org/download, close and reopen the terminal, and retry. If npx asks permission to download the package, review the package and source before entering y.
Benefits of using Kimi API
Using Kimi in Cursor API workflows can improve coding, debugging, and development tasks. Its advanced capabilities help generate accurate responses, handle complex instructions, and support faster problem-solving. Here are the key benefits of using Kimi in Cursor workflows to boost productivity and efficiency.
Long-context code understanding
Kimi can process large amounts of code and information at once. It recognizes relationships between different files and project sections more effectively. As a result, working with large or complex codebases becomes much easier.
Better documentation and repository analysis
Project documents, technical notes, and repositories can be reviewed quickly with Kimi. Important details are easier to find without going through every file manually. Developers can gain a clearer understanding of the entire project in less time.
Cost-effective AI development
Kimi gives a practical and budget-friendly option for handling many development tasks. Powerful AI support is available without depending entirely on higher-cost models. Teams can improve overall productivity while keeping expenses under better control.
Faster knowledge retrieval
Useful information can be located quickly across large codebases, datasets, and project files. Less time is spent searching through resources for answers or references. More attention can be given to coding, testing, and project improvement.
Improved workflow automation
Repetitive development tasks become easier to manage and complete with Kimi. It can assist with code generation, content review, and routine project activities. Daily workflows stay organized, efficient, and more productive over time.
How Codex improves the development workflow
A configured Codex CLI API workflow connects repository inspection, editing, commands, and review in one context. Codex can scaffold files, explain unfamiliar modules, reproduce failures, propose tests, and run approved checks. External provider support adds model choice but does not remove review responsibility.
Start each task with a narrow goal. Ask Codex to inspect before editing, review its proposed changes, approve only commands you understand, run the repository's tests, and inspect the final diff. Treat generated code as an untrusted contribution until it passes review and verification.
Conclusion
Reliable Codex API usage comes from testing each layer in order: authenticate Codex, call Kimi directly, start and test localhost, save the user-level provider configuration, run a read-only prompt, and complete a file-and-tool task. Keep the real Kimi key with the router, keep secrets out of shared files, and stop the router when you finish.