Windo.Me

OpenAI Codex 命令列工具（CLI）使用技巧完整教學

—

by

Antonio Cheong
in , , ,

OpenAI Codex CLI 是一款在終端機中運行的 AI 程式碼助理。它能讀取、修改並執行本機程式碼，協助你更快打造功能、修復臭蟲，並理解陌生代碼。本文提供從入門到進階的完整教學，最後附上 VS Code 的整合方式，以及完整的 deep-search 參考來源清單（可點擊）。

工具簡介與安裝方法

Codex CLI 是什麼？
Codex CLI 是 OpenAI 推出的本機端「輕量程式化代理（coding agent）」，能在你的終端機內與專案互動：導覽檔案、編輯代碼、執行命令與測試。它是開源專案，並持續在 GitHub 上更新。

基本需求

  • 作業系統：macOS、Linux（Windows 建議用 WSL2）
  • Node.js（建議 LTS 版本）
  • OpenAI 帳戶（API 金鑰或可登入的付費帳戶）

安裝 Codex CLI

# 以 npm 全域安裝
npm install -g @openai/codex

# macOS 也可：
brew install codex

# 啟動互動式 CLI
codex

設定 API 金鑰（選擇性）

# macOS / Linux
export OPENAI_API_KEY="<你的金鑰>"

# Windows PowerShell
$env:OPENAI_API_KEY="<你的金鑰>"

初學者：如何與 Codex 互動

  • 互動模式：直接執行 codex，進入對話界面，逐步討論與迭代。
  • 一次性指令：codex "你的請求"，執行一次並結束，適合腳本化。

示例：生成 Python 階乘函式

請用 Python 定義 factorial(n)，n < 0 拋出錯誤，否則回傳階乘。 
def factorial(n: int) -> int:
  """計算 n 的階乘"""
  if n < 0:
    raise ValueError("n 必須是非負整數")
  return 1 if n in (0, 1) else n * factorial(n - 1)

解釋正規表達式／既有代碼

codex "Explain regex: ^(?=.*[A-Z])(?=.*[a-z])(?=.*\d)[A-Za-z\d]{8,}$"

提示撰寫建議：在要求中清楚指明語言（Python、JS、TS…）、框架（React、FastAPI…）與輸出期望（加中文註解、遵循某風格）。提供上下文能顯著提升結果品質。

中階：結合本地檔案、風格與範本

把本地檔案當上下文（在專案根目錄執行）：

codex "Explain the functions in utils/date.ts"

你也能要求撰寫測試、文件註解或做重構建議（Codex 會產生 diff，讓你審核後套用）。

指定語言與風格
在提示內明確要求：「請用 TypeScript 並遵循 Airbnb 風格」或「依 PEP8 調整格式並加上中文註解」。

提示範本（Prompt Template）
以「函式＋使用範例」、「依既有 HTML 模板產生頁面」等方式，能讓輸出更貼近預期。

持久化上下文與指令檔

  1. ~/.codex/instructions.md：全域偏好（註解風格、語氣、輸出格式）。
  2. 專案根目錄 codex.md：專案規範（風格、禁用事項、命名約定）。
  3. 子資料夾 codex.md：區域規則，會與上層疊加（就近優先）。

若暫時不想載入專案說明，可加入 --no-project-doc。

進階：自動化、與 CLI 串接、打造自訂助手

非互動模式 & 腳本整合

  • 一次性請求：codex "你的指令"
  • 或使用子命令：codex exec "fix the CI failure"（執行後退出）。
  • 在 CI 中建議加 -q/--quiet 降噪。

GitHub Actions 範例

- name: Update changelog via Codex
  run: |
    npm install -g open-codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    open-codex -a auto-edit --quiet "update CHANGELOG for next release"

審批模式（Approval Modes）

  • Suggest（預設）：僅提案、不自動改檔，最安全。
  • Auto-Edit：可自動修改檔案；執行命令前仍會詢問。
  • Full-Auto：全自動修改與執行；務必搭配 Git 以利回滾。

啟動時用旗標設定：--approval-mode（或 --auto-edit、--full-auto）。在對話中亦可用 /approvals 切換。

與其他 CLI 串接
Codex 可以組合並執行 Shell 指令（例如 npm install、git mv 批次改名、pytest 跑測試），把繁瑣工作交給自然語言。

自訂別名／打造個人助手

alias codex-summary='codex "生成本專案的架構摘要並列出主要模組"'

你也可調整 ~/.codex/ 設定（預設模型、提供者、推理參數），或透過 MCP 連接外部工具／資料源（安全評估後再用）。

常見錯誤與除錯

  • 認證／連線：檢查 OPENAI_API_KEY，必要時使用 codex login 重新登入；留意企業防火牆／Proxy 設定。
  • 權限／依賴：確認目錄讀寫權限、必需工具在 PATH；先安裝依賴再重試。
  • Windows：建議於 WSL2 執行；或使用 Git Bash 提供類 Unix Shell。
  • 用量／速率限制：關注帳戶配額；必要時改用較小模型或降低頻率。
  • 請求卡住：Ctrl+C 中斷、改小步驟、加 --verbose；保持 CLI 為最新版。

Codex 在 VS Code 的整合與優勢

  • 無縫體驗：不離開編輯器即可生成／修改／解釋代碼。
  • 自動上下文：以目前檔案或選取區塊當上下文，減少貼上動作。
  • 更直觀審核：IDE 內提供 diff 高亮與一鍵套用。
  • 版本控制整合：與 Git 面板協作、PR 檢視更順暢。

總結

  • 以 Suggest 模式起步，熟悉後再提高自動化等級。
  • 活用 上下文與指令檔，建立專案專屬的 AI 助手。
  • 把 Codex 納入腳本與 CI/CD，讓日常自動化更順手。
  • 遇到問題按章除錯並保持更新。

現在就打開終端，讓 Codex 成為你的日常編程拍檔吧！

參考資料

Comments

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *