# Codex App 配置指南

> 在 macOS 與 Windows 上安裝 OpenAI Codex App，並通過 config.toml 接入 LLMoxy 的 Grok 4.7。

> **適用範圍**
> 本文只講 Codex App 接入 LLMoxy，示例模型統一使用 `grok-4.7`。如需終端版，請參考「CodeX CLI 配置指南」。

![Codex App 界面預覽](https://tw.llmoxy.com/docs-assets/migrated/tutorial-codex-app/app-screenshot-light.webp)

## 準備工作

開始前先準備三件事：

1. 一個可用的 [LLMoxy](https://llmoxy.com/) 賬號
2. 一個 **auto** 分組的 LLMoxy API Key
3. 本文統一使用的模型名：`grok-4.7`

Codex App 與 Codex CLI、IDE 插件共享 Codex 配置層。用戶級配置通常放在 `~/.codex/config.toml`；Windows 原生模式下對應 `%USERPROFILE%\.codex\config.toml`。

## 通用 LLMoxy 配置

後面的 macOS、Windows Native、Windows + WSL 都會用到同一段配置。把它寫入對應環境里的 `config.toml`：

```toml
model_provider = "llmoxy"
model = "grok-4.7"
model_reasoning_effort = "high"
model_verbosity = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.llmoxy]
name = "LLMoxy"
base_url = "https://llmoxy.com/v1"
wire_api = "responses"
requires_openai_auth = false
env_key = "LLMOXY_API_KEY"
```

配置含義：

- `model_provider = "llmoxy"`：默認使用下方定義的 LLMoxy Provider
- `model = "grok-4.7"`：默認調用 LLMoxy 上的 Grok 4.7
- `base_url = "https://llmoxy.com/v1"`：Codex 的 OpenAI 兼容端點需要帶 `/v1`
- `wire_api = "responses"`：使用 `/v1/responses`。Codex 只支援這一種，填 `chat` 會直接報錯
- `env_key = "LLMOXY_API_KEY"`：API Key 從環境變量讀取，不寫進配置文件
- `approval_policy` 與 `sandbox_mode`：保留確認和工作區沙箱，適合普通用戶起步

## macOS 安裝與配置

### 1. 安裝 Codex App

打開官方 macOS 下載地址：

- [https://persistent.oaistatic.com/codex-app-prod/Codex.dmg](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

下載後雙擊 `.dmg`，按系統提示把 Codex 拖入 `Applications`。

### 2. 寫入配置文件

打開終端，創建 Codex 配置目錄：

```bash
mkdir -p ~/.codex
open -a TextEdit ~/.codex/config.toml
```

把上面的「通用 LLMoxy 配置」粘貼進去並保存。

### 3. 設置 API Key

macOS 默認 Shell 通常是 Zsh，寫入 `~/.zshrc`：

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="你的LLMoxy API Key"'
} >> ~/.zshrc
source ~/.zshrc
```

驗證：

```bash
echo "$LLMOXY_API_KEY"
```

你必須把 `你的LLMoxy API Key` 替換為控制台里複製的真實令牌。

### 4. 打開項目驗證

啟動 Codex App，選擇一個代碼目錄，然後發送一個輕量任務：

```text
解釋當前項目結構，並指出入口文件在哪裡。
```

如果 Codex 能正常讀取項目並回復，說明 macOS 側已經接入 LLMoxy。

## Windows Native 安裝與配置

![Codex App Windows 界面](https://tw.llmoxy.com/docs-assets/migrated/tutorial-codex-app/codex-windows-light.webp)

Windows 默認使用 **Windows Native Agent**，命令在 PowerShell 環境執行，配置文件在 Windows 用戶目錄下。

### 1. 安裝 Codex App

任選一種方式：

- Microsoft Store 頁面：[Codex App](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US)
- PowerShell 安裝：

```powershell
winget install Codex -s msstore
```

### 2. 寫入配置文件

用 PowerShell 創建並打開配置文件：

```powershell
New-Item -ItemType Directory -Force "$HOME\.codex"
notepad "$HOME\.codex\config.toml"
```

把「通用 LLMoxy 配置」粘貼進去並保存。

實際路徑通常類似：

```text
C:\Users\你的用戶名\.codex\config.toml
```

### 3. 設置 API Key

推薦寫入 Windows 用戶級環境變量：

```powershell
[Environment]::SetEnvironmentVariable("LLMOXY_API_KEY","你的LLMoxy API Key","User")
```

關閉 Codex App 和 PowerShell，重新打開後驗證：

```powershell
echo $env:LLMOXY_API_KEY
```

### 4. 打開項目驗證

啟動 Codex App，添加項目目錄後發送：

```text
執行 git status，並解釋當前工作區狀態。
```

如果 PowerShell 執行策略阻止腳本運行，可在 PowerShell 中執行：

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

如果 Git 功能不可用，先安裝原生 Git：

```powershell
winget install Git.Git
```

## Windows + WSL 配置

如果你的項目主要在 Linux 工具鏈里開發，可以把 Codex Agent 切到 WSL。

![切換到 WSL Agent](https://tw.llmoxy.com/docs-assets/migrated/tutorial-codex-app/wsl-select-light.webp)

### 1. 切換 Agent

在 Codex App 中打開 `Settings`，把 Agent 從 Windows Native 切換到 WSL，然後重啟 App。這個設置重啟後才會生效。

### 2. 寫入 WSL 內配置

切到 WSL 終端後創建配置：

```bash
mkdir -p ~/.codex
nano ~/.codex/config.toml
```

把「通用 LLMoxy 配置」寫入 WSL 內的 `~/.codex/config.toml`。

### 3. 設置 WSL 內 API Key

Bash 用戶：

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="你的LLMoxy API Key"'
} >> ~/.bashrc
source ~/.bashrc
```

Zsh 用戶：

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="你的LLMoxy API Key"'
} >> ~/.zshrc
source ~/.zshrc
```

驗證：

```bash
echo "$LLMOXY_API_KEY"
```

Windows Native 和 WSL 是兩個環境。Agent 跑在 WSL 時，要改 WSL 里的 `~/.codex/config.toml`，也要在 WSL 里設置 `LLMOXY_API_KEY`。

## 常用 App 設置

### 默認打開編輯器

可以在設置里選擇默認 `Open In` 編輯器，例如 VS Code 或 Visual Studio。

![設置默認打開編輯器](https://tw.llmoxy.com/docs-assets/migrated/tutorial-codex-app/open-in-windows-light.webp)

### 集成終端

Windows 下集成終端可以選擇 PowerShell、Command Prompt、Git Bash 或 WSL。這個設置和 Agent 運行環境是兩件事：你可以讓 Agent 跑 WSL，同時集成終端仍使用 PowerShell。

![設置集成終端](https://tw.llmoxy.com/docs-assets/migrated/tutorial-codex-app/integrated-shell-light.webp)

修改終端後通常只對新會話生效，必要時重啟 Codex App。

## 常見問題

### 啟動後仍要求登錄 OpenAI

確認當前環境的 `config.toml` 已寫入：

```toml
model_provider = "llmoxy"
```

並確認 `LLMOXY_API_KEY` 能在同一個環境里讀取到。使用 LLMoxy Provider 時，Codex 會用環境變量里的 API Key 調用 LLMoxy，不需要把密鑰寫入配置文件。

### 404 或模型不存在

檢查三項：

1. `base_url` 必須是 `https://llmoxy.com/v1`
2. `model` 必須是 `grok-4.7`
3. API Key 建議使用 **auto** 分組令牌

### Windows 和 WSL 配置不一致

看 Agent 跑在哪個環境：

- Windows Native：改 `%USERPROFILE%\.codex\config.toml`，設置 Windows 用戶環境變量
- WSL：改 WSL 內 `~/.codex/config.toml`，設置 WSL Shell 環境變量

### 想重置為更保守的權限

保持以下配置即可：

```toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

這會讓 Codex 在需要越過沙箱或執行敏感操作時先詢問。

## 參考鏈接

- [OpenAI Codex App](https://developers.openai.com/codex/app/)
- [OpenAI Codex App for Windows](https://developers.openai.com/codex/app/windows/)
- [OpenAI Codex 配置基礎](https://developers.openai.com/codex/config-basic)
- [OpenAI Codex 認證說明](https://developers.openai.com/codex/auth)

本文是 https://tw.llmoxy.com/docs/code-tutorials/codex-app 的 markdown 版本。
