Coding CLI Helper 安裝指南

English | 繁體中文 | 简体中文

概述

此工具支援安裝和配置 Claude Code、OpenAI Codex 和 Claude Code Router 等強大的 AI 驅動命令列介面，適用於 Windows、macOS 和 Linux 系統。本指南將幫助您使用自動化安裝程式快速設定這些 CLI 工具，並提供域名專屬的最佳化配置。

注意：本教學中的截圖為 Windows 環境，但 macOS 和 Linux 的操作流程基本相同，因為這是一個命令列工具。

快速安裝

SWRD Linux 使用者須知：SWRD 環境下的 Linux 系統已預安裝 Claude Code 和 Codex。Claude Code 可直接使用，Codex 需透過本腳本進行安裝配置，會自動設定 config.toml 檔案。其他系統使用者仍需手動安裝。

Linux/macOS

僅安裝：

curl -fsSLk https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/raw/branch/main/scripts/install.sh | bash

Windows

僅安裝：

powershell -ExecutionPolicy ByPass -c "[System.Net.ServicePointManager]::ServerCertificateValidationCallback={$true}; irm https://gitea.mediatek.inc/IT-GAIA/coding-cli-helper/raw/branch/main/scripts/install.ps1 | iex"

Windows 使用者重要提示：使用工具前，您需要：

1. 提交申請單請 IT 協助打開 git-bash 防火牆
2. 審批通過後，請自行安裝 git-bash 後使用 Claude Code 和 Codex

注意：Linux 和 macOS 使用者無需此操作。

安裝程式會自動：

• 偵測您的平台和架構
• 下載最新版本
• 安裝執行檔並設定 PATH
• 設定必要的權限
• （可選）執行設定來配置 Claude Code、Codex 和 Claude Code Router
• 設定域名專屬的 OTEL 遙測功能（適用於 SWRD 和 MPD 環境）

注意：安裝後請重新啟動終端機以套用 PATH 變更。

手動安裝步驟

步驟 1：下載安裝包

前往發佈頁面下載對應您作業系統的安裝包： 🔗 AI 程式碼助手發佈頁面

步驟 2：解壓縮檔案

將下載的 zip 檔案解壓縮到容易存取的位置，建議選擇可以輕鬆從終端機或命令提示字元開啟的資料夾。

步驟 3：設定安裝選項

安裝程式啟動後，您會看到主選單, 請選擇需要的功能

⏳ 請耐心等候：此步驟包含 Node.js v22、Claude Code CLI、Codex CLI 和 Claude Code Router 的下載與安裝，可能需要幾分鐘時間（共 6 個步驟）。

💡 安裝輸出顯示：安裝程式現在會在每個步驟下方以較淡的顏色即時顯示命令輸出，讓您更容易監控安裝進度和診斷問題。輸出最多顯示 50 行，即使步驟完成後也會保持可見。如需查看完整的輸出歷史記錄，請按 'D' 鍵。

步驟 4：完成安裝

安裝成功後會顯示完成畫面：

完成 開始使用

1. 開啟新的終端機/命令提示字元（重要：需要新視窗才能載入環境變數）

2. 執行 Claude Code：

   claude

添加 Plugin

啟動 Claude Code 後，您可以透過添加 plugin 來擴展功能：

1. 啟動 Claude Code：

   claude

2. 使用 /plugin 指令添加 plugin：

   /plugin

   

   或者：使用直接指令一步完成 plugin 安裝：

   /plugin marketplace add [email protected]:IT-GAIA/claude-code.git

3. 透過 Gitea 連結添加 plugin（如果使用互動模式）：

   [email protected]:IT-GAIA/claude-code.git

   

4. 完成

詳情可參考 🔗 Claude Code Plugin 🔗 Claude Code Plugin Marketplace

系統需求

| 項目 | 需求 | | ------------ | ---------------------------------------------- | | 作業系統 | Windows 11+、macOS 10.15+、或現代 Linux 發行版 | | Node.js | v22 或更新版本（安裝程式會自動處理） | | 網路連線 | 需要連線以下載套件和進行認證 | | 權限 | 一般使用者權限即可（無需管理員權限） |

域名專屬功能

安裝程式會根據您的網路域名自動設定不同的功能：

OA 域名

• 標準 Claude Code 和 Codex 安裝
• 使用 Stop hook 進行對話分析
• 預設 npm registry，失敗時自動切換至聯發科鏡像站

SWRD 域名

• 包含 Claude Code Router 安裝
• 啟用 OTEL 遙測功能，端點：https://mtklm-swrd.mediatek.inc/claude-code-otel
• 自動透過 MTKID 進行使用者追蹤
• 使用域名專屬的 npm registry 鏡像站

MPD 域名

• 包含 Claude Code Router 安裝
• 啟用 OTEL 遙測功能，端點：https://mtklm-mpd.mediatek.inc/claude-code-otel
• 自動透過 MTKID 進行使用者追蹤
• 使用域名專屬的 npm registry 鏡像站

注意：安裝程式會透過網路連線檢查自動偵測您的域名。如有需要，您可以使用 --domain 參數手動指定域名。

疑難排解

❌ 「claude: command not found」錯誤

解決方法：

1. 重新開啟終端機：關閉目前的終端機並開啟新的，讓 PATH 環境變數生效

2. 檢查 PATH 設定：確認 npm 的全域 bin 目錄已加入 PATH

   # 檢查 npm 全域目錄
   npm config get prefix

🔧 Node.js 安裝問題

macOS/Linux

• 安裝程式會在 Debian/Ubuntu 系統上自動嘗試使用 NodeSource 22.x
• 如果自動安裝失敗，請手動安裝：
  1. 前往 Node.js 官網 下載 v22+ 版本
  2. 安裝完成後重新執行安裝程式

Windows

• 安裝程式會使用內建的 Node.js 安裝包
• 自動安裝至 %USERPROFILE%\.cchelper\nodejs
• 如有問題，請確認該目錄的權限設定

🔐 認證問題

常見問題與解決方法：

1. GAISF Token 設定失敗

   • 檢查 MediaTek 網路連線
   • 確認安裝程式在建置時有正確嵌入服務 JWT（OA_JWT / SWRD_JWT）
   • 手動開啟 GAISF 登入頁面取得 Token

2. API 連線問題

   • 確認防火牆設定
   • 檢查公司網路政策
   • 聯繫 IT 部門確認網路存取權限

3. Codex API Key 過期

   當您的 Codex API key 過期時，需要透過以下指令更新：

   ~/.cchelper/coding-cli-helper update
   ~/.cchelper/coding-cli-helper setup

   SWRD Linux 使用者：也可以使用預安裝的輔助工具：

   /etc/claude-code/coding-cli-helper setup

   注意：未來 API key 將延長至半年更新一次。

🍎 macOS 安全驗證錯誤

問題：macOS 顯示「無法驗證開發者」或「惡意軟體」警告，無法執行安裝程式。

解決方法：

• 前往 系統設定 > 隱私權與安全性 > 安全性
• 點擊被阻擋安裝程式訊息旁的 「強制允許」
• 重新執行安裝程式

🔄 重新安裝

如果遇到嚴重問題，可以完全重新安裝：

# Windows
rmdir /s "%USERPROFILE%\.claude"

# macOS/Linux
rm -rf ~/.claude

📋 安裝和可用性問題

問：Claude Code / Codex 目前安裝範圍是哪裡？

答：Claude Code / Codex 目前在 SWRD 的 Linux 上是預設安裝的，但由於 Codex 的使用方式不同，所以如果需要使用 Codex，依然要透過此腳本設定 Config；OA、MPD 用戶請手動安裝。

問：如果 SWRD 下的 Linux 機器沒有 claude / codex 要怎麼辦？

答：可以聯繫 Jason-YS Peng 協助安裝。

問：Windows 使用 Claude Code / Codex 為何會一直報錯？

答：兩個工具官方都建議使用 Linux / MacOS，有可能是 Claude Code / Codex 一直嘗試使用 powershell 指令，可以嘗試請他使用 apply_patch 之類的內建工具來修改檔案。

支援

如遇到任何問題或需要協助，請使用我們的問題追蹤系統：

🔗 尋求協助

尋求協助時，問題模板會引導您提供：

• 網路環境（OA / SWRD / MPD）
• 作業系統（Windows / MacOS / Linux）
• Git-bash 安裝狀態（Windows 使用者）
• 錯誤截圖（如有）
• 系統檢查輸出 ~/.cchelper/coding-cli-helper check --text

直接聯繫：

• ds906659 [email protected]

參考資源

• 📖 Claude Code 官方文件：https://docs.anthropic.com/zh-TW/docs/claude-code
• ⚙️ 設定說明：https://docs.anthropic.com/zh-TW/docs/claude-code/settings

Coding CLI Helper 功能

Coding CLI Helper 內建了分析功能，協助您了解開發活動模式。分析工具可以解析來自 Claude Code 和 Codex 的對話記錄，自動偵測來源類型並提供檔案操作、程式碼異動和開發模式的洞察。

使用方法

分析工具可以直接處理來自 Claude Code 和 Codex 的記錄檔案，或透過 stdin 輸入。工具會自動偵測來源格式並套用適當的分析方法：

# 使用 stdin 模式 (For Claude Code)
echo "{'transcript_path': './examples/test_conversation.jsonl'}" | coding-cli-helper analysis

# 使用 arg 模式 (For Codex)
coding-cli-helper analysis --codex "{'type': 'agent-turn-complete', 'turn-id': '1'}"

# 直接指定檔案路徑分析
coding-cli-helper analysis --path examples/test_conversation.jsonl
coding-cli-helper analysis --path examples/test_conversation_oai.jsonl

# 將分析結果儲存為 JSON 檔案
coding-cli-helper analysis --path examples/test_conversation.jsonl --output examples/analysis_claude_code.json
coding-cli-helper analysis --path examples/test_conversation_oai.jsonl --output examples/analysis_codex.json

# 自訂 o11y 端點（可選）
echo "{'transcript_path': './examples/test_conversation.jsonl'}" | coding-cli-helper analysis --o11y_base_url https://tma.mediatek.inc/api/logs

支援格式：

• Claude Code：包含 parentUuid 欄位的 JSONL 記錄檔
• Codex：來自 Codex 對話的 JSONL 記錄檔（自動偵測）

分析參數

| 參數 | 說明 | | -------------------------- | -------------------------------------------------------------------------- | | --log | 將偵錯日誌寫入 helper 日誌目錄 | | -h, --help | 顯示分析命令說明 | | --o11y_base_url <string> | o11y API 端點基底 URL（預設 https://gaia.mediatek.inc/o11y/upload_locs） | | --output <string> | 將分析結果儲存為 JSON 檔（可選） | | --path <string> | 指定要分析的 JSONL 檔案路徑（stdin 的替代） |

全域參數

| 參數 | 說明 | | ------------------- | ----------------------------------------- | | --domain <string> | 手動指定域（oa/swrd/mpd）以跳過連通性檢查 |

重要檔案說明

| 檔案/目錄 | 用途 | | -------------------------------- | ------------------------------------------------ | | ~/.claude/settings.json | 主要設定檔，包含 API 設定和使用者偏好 | | ~/.cchelper/nodejs/ | Windows 專用：內建的 Node.js 安裝目錄 | | ~/.cchelper/coding-cli-helper | 主要輔助程式安裝位置 | | ~/.local/bin/coding-cli-helper | 輔助程式的符號連結，便於命令列存取 (Linux/macOS) |

注意：在 Linux 和 macOS 上，安裝程式會自動在 ~/.local/bin 建立符號連結以便於存取。請確保 ~/.local/bin 在您的 PATH 中。

輔助指令（Helper Commands）

常用 coding-cli-helper 指令速查表：

核心指令

| 指令 | 說明 | | --------------------------- | ----------------------------------------------- | | coding-cli-helper | 未指定指令時執行安裝程式 TUI（互動式選單） | | coding-cli-helper help | 顯示說明與子指令列表 | | coding-cli-helper version | 顯示版本、建置時間、提交、Go 版本（樣式化輸出） | | coding-cli-helper update | 自我更新輔助程式二進位檔至最新版本 | | coding-cli-helper check | 列印解析後的重要路徑，用於故障排除 |

配置指令

| 指令 | 說明 | | -------------------------------- | ------------------------------- | | coding-cli-helper setup | 設定 Claude Code 和 Codex 配置 | | coding-cli-helper key | 列印 GAISF token（若可用） | | coding-cli-helper switch | 更新配置檔案（標準模式） | | coding-cli-helper switch --oss | 更新配置檔案並套用 OSS 簡化設定 |

分析指令

| 指令 | 說明 | | ----------------------------------------------------------------------------------- | -------------------------------------------- | | coding-cli-helper analysis --path <file> | 從指定的 JSONL 檔案分析對話記錄 | | coding-cli-helper analysis --codex '{"type":"agent-turn-complete","turn-id":"1"}' | 處理 Codex CLI 事件輸入 | | echo '{"transcript_path":"./file.jsonl"}' \| coding-cli-helper analysis | 透過 stdin 分析記錄（Claude Code 模式） | | coding-cli-helper usage | 計算所有工作階段的使用統計（互動式表格檢視） | | coding-cli-helper usage --json | 計算使用統計並輸出原始 JSON |

指令選項

version 指令

• --text - 以純文字格式輸出
• --json - 以 JSON 格式輸出

check 指令

• --text - 以純文字格式輸出
• --json - 以 JSON 格式輸出

setup 指令

• --claude - 僅安裝 Claude Code（包含 Node.js 和配置）
• --codex - 僅安裝 Codex（包含 Node.js 和配置）
• --all - 同時安裝 Claude Code 和 Codex（包含 Node.js 和配置）
• 無標誌：僅設定配置

switch 指令

• --oss - 使用 OSS 簡化配置（先更新所有設定，再套用 OSS 配置）
• 無標誌：僅執行標準配置更新

analysis 指令

• --path <string> - 指定要分析的 JSONL 檔案路徑
• --output <string> - 將分析結果儲存為 JSON 檔
• --o11y_base_url <string> - o11y API 端點基底 URL（預設：https://gaia.mediatek.inc/o11y/upload_locs）
• --codex <string> - 處理 Codex CLI 事件輸入（JSON 格式）
• --log - 將偵錯日誌寫入 helper 日誌目錄

usage 指令

• --json - 輸出原始 JSON 而不是互動式表格檢視

全域選項

• --domain <string> - 手動指定域（oa/swrd/mpd）以跳過連通性檢查
• --setup-folder <string> - 覆寫 .codex 和 .claude 目錄的安裝路徑
• --help - 顯示說明資訊