Codex Base URL Setter

English edition of codex-baseurl-setter.

English | 简体中文

A small macOS utility for changing openai_base_url in your Codex config.toml with a double-click. It creates a backup, checks TOML syntax when a compatible Python installation is available, restores the backup if that check fails, and tests whether the endpoint responds.

Why this exists

Editing the Base URL manually means opening ~/.codex/config.toml. The .codex directory is hidden in Finder, and a missing quote can leave the configuration invalid.

This script makes the process simpler: double-click, paste an address, and confirm the change.

The launchers, prompts, confirmations, error messages, and icon setup instructions are in English.

How to use it

1. Download the project and put Codex-Base-URL.command on your desktop, or wherever you prefer.

2. Before the first run, make the script executable from its containing directory:

   chmod +x Codex-Base-URL.command

3. Double-click the script, paste your address, and press Return. When asked to confirm, enter y and press Return.

If Gatekeeper blocks the first launch, go to System Settings → Privacy & Security and select Open Anyway.

Flexible address input

These inputs all produce the same result. The script fills in the missing scheme and /v1 path:

192.168.1.100:3333
http://192.168.1.100:3333
http://192.168.1.100:3333/v1
"http://192.168.1.100:3333/v1/"

It removes quotation marks, whitespace, and a trailing slash.

What happens when you confirm a change

Step	What it does
Backup	Saves a copy as ~/.codex/config.vN.toml, choosing an unused number so existing backups are preserved.
Update	Replaces an existing openai_base_url line, or inserts it at the beginning of the file if none exists.
Syntax check	Parses the file with Python's tomllib, if available.
Restore on failure	Copies the backup back into place if the syntax check fails.
Connectivity check	Requests {URL}/models. HTTP 200, 401, or 403 is treated as evidence that the endpoint is reachable; this does not verify successful authentication.

Pressing Return without entering an address, or entering the current address, leaves the file unchanged.

After changing the address, fully quit Codex with Cmd+Q and reopen it. Closing the window alone is not enough.

Optional custom icon

Double-click Set-Icon.command to make the script easier to recognize on your desktop. Keep it alongside Codex-Base-URL.command and the assets folder.

This requires PyObjC (pip3 install pyobjc-framework-Cocoa). You can also set the icon manually:

1. Open assets/icon.png in Preview, press Cmd+A to select all, then Cmd+C to copy.
2. Select Codex-Base-URL.command and press Cmd+I to open Get Info.
3. Click the small icon in the top-left corner and press Cmd+V to paste.

The icon is stored in the file's extended attributes (com.apple.ResourceFork and com.apple.FinderInfo). To preserve it, edit the script in place with an editor or sed -i ''. Deleting and recreating the file, or replacing it with another copy, can remove the icon.

The original Chinese launcher filenames are kept as compatibility shortcuts. Keep them in the same folder as the English launchers if you use them.

Requirements

• macOS
• An existing ~/.codex/config.toml file
• Python 3.11+ with tomllib for syntax validation. If unavailable, validation is skipped and the other steps still run.
• curl, included with macOS

Disclaimer

This script modifies your ~/.codex/config.toml. It creates a backup before each change, but you should verify that the backup exists. The author is not responsible for data loss.

License

PolyForm Noncommercial 1.0.0 — see LICENSE. The original license and its bilingual permission notice are preserved unchanged.

You may use, modify, study, and share the project for noncommercial purposes. Commercial use requires the author's prior written permission, including internal business use, inclusion in a paid product, or use as part of a paid service.