Mac Codex CLI Claude CLI 更新重裝指南：官方指令與錯誤排查

AI
, , , ,
1

整理 Codex CLI 與 Claude CLI 官方推薦更新方式、內建升級指令、Homebrew/npm 差異，附完整重裝步驟與 claude doctor 診斷技巧，解決依賴衝突與版本問題。

核心更新方式對照

工具 官方推薦更新方式 內建更新指令 備選方式
Codex CLI 重跑安裝腳本 curl -fsSL https://chatgpt.com/codex/install.sh | sh codex --upgrade brew upgrade --cask codex / npm install -g @openai/codex@latest
Claude Code 重跑安裝腳本 curl -fsSL https://claude.ai/install.sh | bash claude update brew upgrade --cask claude-code / npm（已淘汰）

關鍵提醒：兩款工具目前都以「原生安裝腳本」為主推管道。Claude Code 已將 npm 方式標示為 Deprecated，建議改用 Homebrew 或官方腳本，避免路徑與版本衝突。

Codex CLI 更新指令詳解

依安裝方式選擇指令

  • Homebrew（官方推薦 Mac）：brew upgrade --cask codex
    • 若原本用 brew install codex（非 cask）則用 brew upgrade codex
  • npm 全域安裝：npm install -g @openai/codex@latest 或 npm update -g @openai/codex
  • 內建升級：終端機直接輸入 codex --upgrade
  • 原生腳本安裝：重新執行 curl -fsSL https://chatgpt.com/codex/install.sh \| sh

驗證版本

codex --version

目前最新穩定版為 0.142.2（2026-06-25 發布）。若更新後版本號未變，通常是殘留舊安裝或快取問題，需先移除重複安裝再重裝。

Claude Code 更新指令詳解

依安裝方式選擇指令

  • 原生安裝腳本（官方推薦）：重新執行 curl -fsSL https://claude.ai/install.sh \| bash
  • Homebrew：初次 brew install --cask claude-code，更新用 brew upgrade --cask claude-code
  • 內建更新（最簡單、最不易出錯）：claude update
  • npm（已淘汰但仍可用）：npm install -g @anthropic-ai/claude-code

驗證版本

claude --version

或觀察 claude update 執行後的輸出訊息。目前版本 v2.1.199，Sonnet 5 為預設模型，新增 Agent View、plugins、hooks 等功能。

常見依賴錯誤與根因

工具 常見錯誤 根因
Codex CLI Missing optional dependency @openai/codex-darwin-x64（或 arm64） npm 平台專屬二進位檔未正確下載，或 ~/.npmrc 殘留錯誤 os 設定
Claude Code EBADENGINE 警告（npm 安裝時） v2.1.198 後要求 Node.js 22+，版本過舊觸發
Claude Code 路徑衝突、launcher 衝突 多重安裝（npm + Homebrew + 原生腳本）共存導致

注意：Claude Code 原生腳本直接下載對應平台二進位檔，不透過 Node.js 執行，因此較少出現平台套件錯誤。

Codex CLI 完整重裝流程（解決依賴錯誤最徹底方案）

  1. 卸載現有版本
    # npm 安裝
npm uninstall -g @openai/codex
# Homebrew 安裝
brew uninstall codex          # 或 brew uninstall --cask codex
  2. 清除設定與快取殘留
    rm -rf ~/.codex
# 檢查並移除錯誤的 npm 設定
npm config delete os
npm config delete platform
  3. 確認 Node.js 版本（建議用 nvm 管理，Codex CLI 通常要求 Node 22+）
    nvm install 22 && nvm use 22
  4. 清除 npm 全域快取
    npm cache clean --force
  5. 重新安裝（二擇一）
    # 方式 A：npm
npm install -g @openai/codex@latest
# 方式 B：官方腳本（避開 npm 平台套件解析問題）
curl -fsSL https://chatgpt.com/codex/install.sh | sh
  6. 驗證
    codex --version
    若仍報 Missing optional dependency，改用 Homebrew cask 方式安裝。

Claude Code 完整重裝流程（官方標準解除安裝→重裝）

  1. 移除原生安裝的二進位與版本目錄
    rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
  2. 移除 npm 安裝殘留（若曾用 npm）
    npm uninstall -g @anthropic-ai/claude-code
  3. 移除 Homebrew 安裝殘留（若曾用 Homebrew）
    brew uninstall --cask claude-code
# 或 brew uninstall --cask claude-code@latest
  4. 移除設定與快取（:warning: 會清空所有 MCP 設定與 session 記錄，如需保留請先備份）
    rm -rf ~/.claude
rm ~/.claude.json
  5. 檢查殘留 launcher 或 alias 造成衝突
    which claude
# 若出現多個路徑，移除舊有的
  6. 重新執行官方安裝腳本
    curl -fsSL https://claude.ai/install.sh | bash
  7. 驗證與完整診斷
    claude --version
claude doctor   # 官方內建診斷，列出已知問題與修復建議

兩者重裝流程快速對照

步驟 Codex CLI Claude CLI
卸載指令 npm uninstall -g @openai/codex 或 brew uninstall codex npm uninstall -g @anthropic-ai/claude-code 或 brew uninstall --cask claude-code
設定殘留清除 rm -rf ~/.codex，檢查 ~/.npmrc rm -rf ~/.claude rm ~/.claude.json
二進位殘留清除 無固定目錄，主要靠 npm/brew 管理 rm -rf ~/.local/share/claude rm -f ~/.local/bin/claude
重裝來源 官方腳本或 npm install -g @openai/codex@latest curl -fsSL https://claude.ai/install.sh | bash
診斷工具 codex --version（無內建 doctor） claude doctor（官方內建完整診斷）

實務建議與避坑指南

  1. 優先使用官方推薦管道：兩者皆以原生安裝腳本為主推，Homebrew 為次選，npm 為最後備選（Claude Code 已淘汰）。
  2. 避免多重安裝共存：同時存在 npm、Homebrew、原生腳本安裝最易造成 which claude/which codex 路徑衝突。
  3. 遇到依賴錯誤先跑診斷：Claude Code 有 claude doctor，務必先執行；Codex CLI 則優先檢查 Node.js 版本（≥22）與 ~/.npmrc 設定。
  4. 重裝前備份設定：Claude Code 的 ~/.claude 與 ~/.claude.json 包含 MCP 設定與 session 記錄，重裝前請先複製備份。
  5. Node.js 版本管理用 nvm：避免系統級 Node 版本衝突，確保符合工具最低版本需求。

結語

掌握 官方推薦更新指令、內建升級指令（codex --upgrade、claude update）、完整重裝流程與 診斷工具（claude doctor），即可在 Mac 上穩定維護 Codex CLI 與 Claude Code 的最新版本。遇到依賴錯誤時，完全移除＋清除快取＋重新安裝 是最高效的解決路徑，尤其注意避免多重安裝管道共存造成的路徑衝突。