ChatGPT / Codex Setup

Codex is OpenAI's official command-line AI coding assistant. Connect it through the 4AICode API to manage keys, team quotas, and usage in one console, with billing based on actual token usage.

💡 Beginner tip: We recommend starting with [Method 1: Connection Assistant (GUI)]. You don't need to type commands—configure everything with just a few clicks.

Prerequisites: Get Your Token

Whichever setup method you choose, you first need your 4AICode token:

1. Sign in to 4AICode and go to Dashboard → Manage Tokens.
2. Click "New Token".
3. Copy the generated string (formatted like sk-4ai-<your-token>).

⚠️ Important notes:

• The token is shown only once upon creation. Save it to a password manager or notes app.
• sk-4ai-<your-token> in this guide is a placeholder. Replace it with your actual token.
• When using command-line examples, replace the angle brackets and their placeholder contents with your actual token.
• Treat your token like a password: never share it or commit it to GitHub.

Method 1: Connection Assistant (Recommended for Beginners)

The 4AICode Connection Assistant uses MyGo to build its native desktop interface and requires no terminal commands.

1. Download the Connection Assistant

The Windows build currently has no publisher signature and may show a SmartScreen prompt on first launch. Defender validation is pending. From the download directory, run certutil -hashfile 4aicode-assistant-windows-amd64.exe SHA256 (Windows) and compare it with the hash at the start of the matching file line in SHA256SUMS.txt.

Both macOS architectures use Developer ID signing and Apple notarization. Open the DMG and drag the app into Applications to install.

(Checksum verification: SHA-256 Checksums · Version info)

The download link shows the release version. Before updating, choose Quit from the assistant’s system tray/menu bar; closing its window keeps it running. Replace the app and reopen it, then compare the version and build ID at the top right of the window with the download page.

2. Configure in 3 Simple Steps

1. Connect Account: Open the assistant, paste your sk-4ai-<your-token>, select Mainland China (国内线路) or International (国际线路), then choose a model from the dropdown loaded automatically from that route’s API and click "Connect". Changing the token or route reloads the models; use Refresh Models (刷新模型) to retry.
2. Install & Launch: Click "Select Project & Launch Codex". On first use, if Codex CLI is missing, the assistant downloads and installs it before launching it in your chosen directory. The assistant shows a status message while downloading; wait for it to finish.
3. Keep it available: Closing the window keeps the assistant in the system tray (Windows) or menu bar (macOS) for quick access.

Your token is saved securely in the system credential manager. Click the eye icon beside the input to show or hide what you entered. Connecting hides it again.

3. Connect the Official Windows Desktop App

Local Codex supports API-key sign-in and can use your 4AICode balance directly:

1. Select a model and connect in the assistant. The model list supports mouse-wheel scrolling and keyboard selection.
2. Click Copy Desktop Login Key (复制桌面登录密钥). The assistant prepares the desktop provider configuration and copies its local connection key.
3. Fully quit and reopen the official ChatGPT / Codex desktop app. Choose Sign in another way → API key, paste into OpenAI API key, and continue.
4. Keep the assistant running and start a new local task. Restart the desktop app after changing the model or route.

Use the same Windows user and Codex configuration directory for both apps (normally %USERPROFILE%\.codex). If you set CODEX_HOME, both apps must use that directory.

Treat config.toml as private because it contains the local connection key. Redact credentials before sharing troubleshooting information. Restore Original Configuration exits the assistant's desktop sign-in mode.

The copied key connects to the local assistant; your 4AICode token stays in the system credential vault. Users already signed in with ChatGPT can keep their login, click this button, and restart the app. API-key mode supports local Codex work. ChatGPT web chat, workspace, and cloud features use their respective official account permissions. Official authentication documentation

Desktop error: Model provider fouraicode_assistant not found

The configuration loaded by the desktop app is missing the assistant's provider definition:

1. Quit the old assistant from the system tray, download the latest version, and click Connect (连接). If it still shows connected, click Disconnect (断开) and connect again. From v0.1.2, the assistant checks configuration regularly and can restore a missing definition on reconnect when its backup confirms ownership.
2. Fully quit and reopen the official ChatGPT / Codex desktop app, then open the affected conversation.
3. If the error persists, check that both apps use the same Windows user and configuration directory, including CODEX_HOME when set. Share the assistant version, steps, and configuration directory with support.

After using Restore Original Configuration, reconnect before continuing an assistant conversation. To use your original provider, restart the desktop app and start a new task.

Connection settings changed

Click Reconfigure and Connect (重新配置并连接), then confirm Back Up and Connect (备份并连接). The assistant saves your current settings and previous backup before switching to 4AICode, preserving project trust, MCP, and other providers. Restoring afterwards returns to the settings from before this switch. Restart the desktop app when finished.

Connection failed

Follow the specific message: retry a timeout, check the local proxy app and port for proxy failures, check the computer's date and time for certificate failures, or refresh an invalid model list. Contact support for persistent service errors. Handle token, balance, and usage-limit messages in the dashboard. Share the assistant version and error message with support; redact credentials before sharing configuration files.

Method 2: Command-Line Setup (For Developers)

If you are comfortable using the terminal, run the install command and one-click setup script. It takes about 2 minutes.

# Option A: via npm (recommended, requires Node.js 16+)
npm install -g @openai/codex

# Option B: via Homebrew (macOS only)
brew install --cask codex

# International route (recommended)
export RELAY4AI_BASE_URL=https://relay.4aicode.com/v1
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s install 'sk-4ai-<your-token>'

# Mainland China direct route (.net)
curl -fsSL https://4aicode.net/codex-setup.sh | bash -s install 'sk-4ai-<your-token>'

codex

Common Operations

1. Switching Models & Reasoning Effort

With the assistant, click Disconnect, select another model from the dropdown, reconnect, and restart Codex.

For command-line setup, edit the local config file:

• macOS / Linux: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

Update these two lines (leave other fields intact):

model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"

Reasoning effort options: low, medium, high, xhigh. Changes take effect after restarting Codex.

2. Check Status or Rollback Configuration

# Check current provider and model status
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s status

# Uninstall and restore pre-setup config
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s uninstall

Troubleshooting & FAQ

Q1: codex: command not found or not recognized?

• Cause: Codex CLI is not installed or your terminal environment path has not refreshed.
• Fix: Close the current terminal and open a new one. If it persists, ensure Node.js is installed and re-run npm install -g @openai/codex.

Q2: Encountered 401 Unauthorized?

• Cause: Invalid or revoked token, or placeholder was not replaced.
• Fix: Check whether sk-4ai-<your-token> was replaced with your actual token. You can generate a new token in the Dashboard and rerun the setup command.

Q3: PowerShell blocks the script with execution policy error?

• Fix: Use the & ([scriptblock]::Create(...)) command shown above, or run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned in PowerShell to allow local scripts.

Q4: Config or model changes don't take effect?

• Fix: Codex caches configuration upon startup. Completely exit Codex CLI or close the Codex App, open a fresh terminal, and run codex again.

Q5: How to use the official Codex desktop app (Codex App)?

• Connect in the assistant, click Copy Desktop Login Key (复制桌面登录密钥), fully quit and reopen the desktop app, then choose API-key sign-in and paste. See the Windows desktop instructions above.
• To return to an official provider, restore the original configuration in the assistant. If you signed in with the local key, sign out in the desktop app and select your own official sign-in method.

Other Tools & SDK Integration

If you use other editors or SDKs, connect them to 4AICode's ChatGPT pool with standard OpenAI-compatible parameters:

API Parameters

• Base URL: https://relay.4aicode.com/v1 (or https://relay.4aicode.net/v1 in mainland China)
• API Key: Your 4AICode Token (sk-4ai-<your-token>)

Python SDK Example

from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-<your-token>",  # Replace with your actual token
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[{"role": "user", "content": "Hello! Please write a quicksort algorithm."}],
)

print(response.choices[0].message.content)

cURL Example

curl https://relay.4aicode.com/v1/chat/completions \
  -H "Authorization: Bearer sk-4ai-<your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [{"role": "user", "content": "ping"}]
  }'

Appendix: Manual Advanced Setup (For Reference)

💡 Standard users can safely ignore this section. Intended for developers who need to review or manually merge configurations.

Config file locations:

• macOS / Linux: ~/.codex/
• Windows: %USERPROFILE%\.codex\

1. auth.json

Retain ChatGPT official login auth structure:

{
  "auth_mode": "chatgpt",
  "OPENAI_API_KEY": null,
  "tokens": {
    "id_token": "...",
    "access_token": "...",
    "refresh_token": "...",
    "account_id": "..."
  },
  "last_refresh": "..."
}

2. config.toml

Set 4AICode as the model provider:

model_provider = "OpenAI"
openai_base_url = "https://relay.4aicode.com/v1"
model = "gpt-5.6-terra"
model_reasoning_effort = "xhigh"

[model_providers.OpenAI]
name = "4aicode"
base_url = "https://relay.4aicode.com/v1"
wire_api = "responses"
experimental_bearer_token = "sk-4ai-<your-token>"
requires_openai_auth = true