第一次用Codex就上手：Windows、Mac安裝與API設定實作

從開啟終端機到收到第一個回覆，保留自動與手動兩條路，最後練習修改本機檔案。

剛開始接觸AI開發工具，未必要立刻交給它一整個專案。比較容易觀察的起點，是建立一個練習資料夾，讓工具回答一個不碰檔案的小問題，再逐步開放檔案操作。

這份教學以「完成一項、確認一項」安排。準備好API資料後，Windows讀者看第2節，Mac讀者看第3節；兩邊都從第4節開始驗證。CLI和桌面應用程式分別安裝，手動設定則保留給想控制每個步驟的讀者。

1. 開始前，準備帳號、模型名稱與練習空間

這次以Crazyrouter示範第三方API。選它是為了展示可替換的接入方式，不表示一定要放棄官方服務。第三方服務可能方便比較模型價格、集中查看用量；是否划算仍要看輸入、輸出費率與實際工作量，也要確認Responses協定及支援方式。若現有ChatGPT訂閱已符合需求，可以先用原本的方案，API費用不等同於訂閱月費。

先到服務網站註冊，依表單填寫帳號、密碼與要求的電子郵件驗證資料。完成後登入控制台，開啟API金鑰管理。官方服務說明將它標為「Token Management」，建立動作為「Create Token」。

網站原始畫面使用簡體中文；本文操作說明採繁體中文。

建立Key後，先檢查有效期限、剩餘額度與模型限制。範例使用gpt-5.6-sol，可在GPT-5.6 Sol模型說明核對API識別名稱；頁面看得到模型，不代表你的Key就有呼叫權限，仍要看帳號設定並實際送出請求。

登入密碼、API Key和模型ID各自有用途，不要混填。自動安裝腳本會詢問Key，不會代為註冊，也不會自動取得免費使用額度。

接著只選自己電腦的操作段落，不必把Windows與Mac指令都執行一次。

2. Windows：在PowerShell完成CLI設定

按Windows鍵，搜尋「PowerShell」，點選開啟。出現PS C:\Users\...>後即可輸入。選取程式碼按Ctrl+C複製，回到視窗按Ctrl+V貼上，再按Enter執行。每次先處理一行，不複製提示符號或程式碼區塊的語言名稱。

希望快速完成：使用自動設定

服務網站的Codex接入頁有自動設定入口，公開腳本原始碼也能由該頁查看。第一次安裝使用以下兩行：

$env:CRAZYROUTER_CODEX_MODE='full'
iwr -UseB https://raw.githubusercontent.com/xujfcn/crazyrouter-codex-cli/main/install-crazyrouter-codex.ps1 | iex

圖中的快捷方式使用switch；初次安裝改用正文列出的full。

full會檢查Git、Node.js與CLI，補齊缺少的元件再設定API。若CLI已經裝好，只要換連線設定，將第一行的'full'換成'switch'。第二行不變；它會下載並執行腳本，第一行沒有訊息則是正常的。

完整安裝可能跳出安裝程式或權限視窗，也使用軟體授權條款接受選項，請核對提示中的軟體後再操作。接著在API Key提示處貼上Key、按Enter；輸入被隱藏時，不要因為看不到字就再貼一次。模型選擇則先確認權限，再接受預設值或填入相容的模型ID。

等結束訊息出現，完全關閉PowerShell或Windows Terminal再開啟。此時直接前往第4節；桌面程式尚未安裝。

想逐項設定：使用手動方式

先從Node.js官方網站下載符合電腦架構的LTS安裝程式，保留PATH選項。安裝完重新開啟PowerShell，依序執行：

node --version
npm.cmd --version
npm.cmd install -g @openai/codex
codex.cmd --version

確認前兩行能顯示版本後，再執行安裝。需要Git時，從Git for Windows官方網站安裝，重開視窗後檢查git --version。

下一組指令先備份舊設定，再用記事本開啟設定檔：

New-Item -ItemType Directory -Path "$env:USERPROFILE\.codex" -Force | Out-Null
$codexConfigPath = Join-Path $env:USERPROFILE '.codex\config.toml'
if (Test-Path -LiteralPath $codexConfigPath) { Copy-Item -LiteralPath $codexConfigPath -Destination ($codexConfigPath + '.backup-' + (Get-Date -Format 'yyyyMMdd-HHmmss')) }
if (-not (Test-Path -LiteralPath $codexConfigPath)) { New-Item -ItemType File -Path $codexConfigPath | Out-Null }
notepad.exe $codexConfigPath

將下列內容貼進記事本，不是貼進PowerShell執行：

model = "gpt-5.6-sol"
model_provider = "crazyrouter"

[model_providers.crazyrouter]
name = "Crazyrouter"
base_url = "https://api.crazyrouter.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

空檔案可以整段貼上；舊檔案請修改相應欄位，保留其他設定。最上面的兩項要位於第一個方括號之前，服務商區段不可重複。按Ctrl+S儲存，避免檔名多出.txt。

env_key指定環境變數名稱，不是讓你在此填入金鑰。

base_url保留/v1，不追加/responses。查核時自動腳本使用cn.crazyrouter.com，手動範例使用api.crazyrouter.com，請保留所選路線的完整設定。

回到PowerShell，先讓它開啟隱藏輸入：

$codexApiKey = Read-Host 'Paste your API Key, then press Enter' -AsSecureString

貼上Key並按Enter，回到一般提示符號後執行：

[Environment]::SetEnvironmentVariable('OPENAI_API_KEY', ([System.Net.NetworkCredential]::new('', $codexApiKey)).Password, 'User')
Remove-Variable codexApiKey

這會更新使用者的同名環境變數，其他工具也可能使用它。完整退出終端程式後重新開啟，接著看第4節。

3. Mac：留意Shell設定與圖形程式的差別

按Command+空白鍵搜尋「終端機」，按Return開啟。本文以zsh為準，若平常使用其他Shell，先輸入zsh。貼上指令使用Command+V，每行按Return執行。

自動安裝

touch ~/.zshrc
curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-codex-cli/main/install-crazyrouter-codex.sh | bash -s -- --full

第一行確保zsh設定檔存在，不清除內容。CLI已經安裝就把末尾--full改成--switch。依提示輸入API Key、選擇模型；系統安裝程式索取密碼時，才輸入Mac登入密碼。

若缺少Git，執行xcode-select --install並完成開發工具安裝，以git --version檢查，再繼續腳本。結束後載入設定並確認CLI：

source ~/.zshrc
codex --version

npm安裝成功卻找不到程式時，先試：

export PATH="$PATH:$(npm config get prefix)/bin"
codex --version

若有效，以nano ~/.zshrc開啟檔案，將export那一行存進去。nano的儲存方式是Control+O、Return，退出是Control+X。自動設定完成即可往第4節。

手動安裝與設定

不用自動腳本時，可直接使用官方CLI安裝器：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

依安裝器提示處理PATH，重開終端機，用codex --version確認。然後建立設定目錄、備份舊檔並開啟編輯器：

mkdir -p ~/.codex
if [ -f ~/.codex/config.toml ]; then cp ~/.codex/config.toml ~/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S); fi
nano ~/.codex/config.toml

將第2節完整的TOML設定貼入nano。模型設定同樣放在第一個區段之前；已有檔案只合併相應欄位，不覆蓋其他內容。用Control+O、Return儲存，再Control+X離開。

接著執行nano ~/.zshrc，新增或修改這行：

export OPENAI_API_KEY='YOUR_API_KEY'

把占位文字換成自己的Key，保留英文單引號。儲存後執行source ~/.zshrc。這份檔案會保存明文金鑰，不放進版本控制，也不拿它當教學截圖。

先讓終端機讀到Key就好，圖形程式的傳遞方式留到第5節一起處理。

4. 第一個任務只問問題，先觀察連線

Windows先在新視窗檢查Key是否存在：

if ([string]::IsNullOrWhiteSpace($env:OPENAI_API_KEY)) { 'KEY_MISSING' } else { 'KEY_FOUND' }

Mac則執行：

if [ -n "${OPENAI_API_KEY:-}" ]; then echo KEY_FOUND; else echo KEY_MISSING; fi

KEY_FOUND僅表示變數有內容。接著建立不含重要資料的練習目錄，Windows使用：

New-Item -ItemType Directory -Path "$env:USERPROFILE\Projects\codex-first-test" -Force | Out-Null
Set-Location "$env:USERPROFILE\Projects\codex-first-test"
codex

Mac使用：

mkdir -p ~/Projects/codex-first-test
cd ~/Projects/codex-first-test
codex

若Windows阻擋codex.ps1，改用codex.cmd。出現目錄信任提示時，確認路徑是自己建立的資料夾。在Codex對話欄貼上：

請用三句話說明README檔案的用途，不要讀取或修改任何檔案。

收到完整說明，才有當次API請求成功的證據。本文採用的Windows實測是在2026年10月14日，以簡體中文的同義問題透過非互動CLI驗證；手動與腳本設定都取得回覆。環境為Node.js24.21.0、npm11.19.0、Git2.53.0、CLI0.162.1，依賴原本已安裝，不代表空白電腦或Mac也完成測試。

建議把成功時間記下來，回控制台查看用量。一次請求除了你輸入的句子，還可能有工具上下文；不要直接把中文字數當成計費Token數。

5. 再加上桌面介面，重用設定但重新驗證

由官方桌面安裝指引下載應用程式。目前文件以“ChatGPT desktop app”稱呼共同介面，啟動後從產品選單切換至Codex。API Key與訂閱登入可用的功能可能有差異，依當前說明操作。

圖中是下載及操作指引，並非本機完成安裝的畫面。

Windows走安裝程式或Microsoft Store提供的流程。若桌面程式早於Key設定就已啟動，完整退出後重開。新增工作資料夾時輸入%USERPROFILE%\Projects\codex-first-test，確認選取，再於新對話送出剛才的問題。

Mac使用者在Apple選單的「關於這台Mac」確認處理器，下載Apple silicon或Intel對應版本，並檢查支援的macOS版本。開啟.dmg後拖入「應用程式」，或依.pkg安裝精靈完成。

處理器不同，對應的安裝套件也不同。

從Dock開啟的程式不會自動載入.zshrc。先按Command+Q退出應用程式，回到終端機載入Key，確認檢查結果為KEY_FOUND後執行傳遞：

source ~/.zshrc
launchctl setenv OPENAI_API_KEY "$OPENAI_API_KEY"

再開啟桌面程式。在資料夾選擇視窗按Command+Shift+G，輸入~/Projects/codex-first-test並確認，送出相同問題。這個傳遞設定只適用目前的圖形登入工作階段，登出或重開機後要重做。

設定共用的前提是相同本機使用者與預設設定目錄。WSL、自訂目錄或其他帳號需要各自核對。這也是桌面端值得單獨驗證一次的原因。

6. 從回覆走到檔案：完成一個看得見的小練習

接下來才試檔案編輯。CLI在對話欄輸入/permissions；桌面版查看輸入框下方的權限控制。官方文件中的Ask for approval允許工作區內操作，超出範圍再要求批准；組織或沙箱的上層限制仍可能生效。

權限文件的實際畫面，不能當成檔案寫入成功的證據。

在練習目錄裡送出：

請在目前資料夾實際建立learning-checklist.md，使用UTF-8編碼。
標題為「我的Codex練習」，列出三個尚未勾選的Markdown工作項目：
- 安裝CLI
- 取得API回覆
- 編輯本機檔案
只建立這個檔案，不安裝軟體，也不改動其他檔案。完成後告訴我路徑。

用檔案總管或Finder進入練習目錄，確定檔案存在，再讓Codex只勾選前兩項。重新開啟檔案檢查：前兩項應是- [x]，第三項維持- [ ]。讓結果留在本機，比只在對話裡看到一段Markdown更容易確認。

先前的測試環境拒絕了寫入，原因是唯讀策略，因此這個練習不列為已通過的實測。若你也遇到，先檢查工作目錄與政策，不必立即開放全部存取權。

日後求助時，最好附上「最後成功的一步」。版本能顯示但401，先查Key；CLI正常、桌面缺Key，查程式啟動時取得的變數；能回覆卻存不了檔案，查權限。若是403，搭配錯誤全文與模型授權判讀，不要只憑狀態碼認定帳號遭停用。

本文使用AI輔助整理與撰寫；圖片為來源頁面的真實截圖。