在開始配置之前，你需要先獲取 API 密鑰（sk-xxx）：
1. 打開 new.your-agent.cc 並註冊賬號
2. 登錄後進入「控制檯」→「令牌」→「新建令牌」
3. 選擇分組（如 claude-antigravity），點擊提交
4. 複製生成的令牌（sk-xxxxxxxx），這就是你的密鑰
5. 告訴管理員你的賬戶名稱
Claude Code 在 Windows 上推薦使用 WSL（Windows Subsystem for Linux）安裝和運行，兼容性最好。如果不想裝 WSL，至少使用 Git Bash 來運行 Claude Code。
PowerShell 兼容性較差，可能遇到文件鎖定、寫入失敗（error write file）等問題。遇到問題多問 AI！
Windows Terminal 是微軟官方的現代化終端工具，支持多標籤頁、更好的字符渲染、emoji 和中文顯示。強烈建議用它替代自帶的 cmd 和 PowerShell 窗口。
Microsoft Store 下載 GitHub 下載
Claude Code 依賴 Git 運行。如果啓動時看到以下錯誤，說明需要先安裝 Git：
安裝時保持默認選項即可。安裝完成後重啓終端，驗證安裝：
Git 已安裝但提示找不到？點擊一鍵自動檢測
如果 Git 已安裝但啓動時提示需要設置 CLAUDE_CODE_GIT_BASH_PATH，在 PowerShell（管理員）中執行以下命令自動檢測並設置：
按 Win+X → 選擇「終端管理員」或「PowerShell(管理員)」
手動查找 Git 安裝位置：
Git 版本要求：Git 2.24.0 及更早版本的 cygpath.exe 無法正確處理中文路徑，會導致 Claude Code 在中文目錄下報錯。建議升級到 Git 2.40+
官方推薦的原生安裝方式，無需 Node.js，自動後臺更新，始終保持最新版本。
優點：
- 無需安裝 Node.js 18+
- 自動後臺更新，始終保持最新版本
- 避免 npm 權限問題
PowerShell 安裝：
中國大陸用戶網絡問題？
如遇網絡問題，可設置代理後安裝：
或使用 npm 鏡像安裝（需先安裝 Node.js）：
WinGet 安裝（Windows）
WinGet 安裝不會自動更新，需定期運行
winget upgrade Anthropic.ClaudeCode
npm 安裝（備選） 已被官方標記爲棄用
需要 Node.js 18+，適合網絡受限用戶使用國內鏡像
安裝 Node.js
方法一：官網下載（推薦）
打開 https://nodejs.org/，下載 LTS 版本，雙擊安裝。
方法二：nvm-windows（多版本管理）
下載 nvm-setup.exe 從 GitHub Releases
國內加速下載：https://static.yoouu.cn/nvm-setup.exe
方法三：包管理器
驗證安裝：
全局安裝：
安裝特定版本
安裝穩定版（約延遲一週，跳過重大問題）：
安裝指定版本號：
從 npm 遷移到原生安裝
如果你之前使用 npm 安裝，可以運行遷移命令：
系統會自動處理遷移，然後驗證安裝：
驗證安裝：
提示 .local\bin 不在 PATH 中？
原生安裝後如果提示路徑不在 PATH 中，在 PowerShell（管理員）中執行：
這是最關鍵的一步！需要配置 API 代理地址和密鑰。將 sk-xxx 替換爲你的密鑰
之前用過其他中轉服務？先清理舊配置
settings.json 中的 env 優先級高於系統環境變量，需先清理。
檢查配置文件：
檢查環境變量：
清理用戶級環境變量：
清理系統級環境變量（需管理員）：
如果 settings.json 中有 env 包含 ANTHROPIC_BASE_URL，需刪除或修改
永久設置（系統級別，需管理員權限）：
按 Win+X → 選擇「終端管理員」或「PowerShell(管理員)」
設置後需重新打開終端生效
驗證環境變量：
不再使用？刪除環境變量
清理用戶級環境變量：
清理系統級環境變量（需管理員）：
驗證是否刪除成功：
在項目目錄下運行：
首次啓動會進行初始化，稍等片刻即可開始使用。
macOS 默認使用 zsh 作爲終端 shell。如果你使用的是較舊版本的 macOS，可能默認是 bash。可以通過
echo $SHELL 查看當前使用的 shell。
推薦使用 iTerm2 或系統自帶的「終端」應用來運行 Claude Code，體驗更佳。
官方推薦的原生安裝方式，無需 Node.js，自動後臺更新，始終保持最新版本。
優點：
- 無需安裝 Node.js 18+
- 自動後臺更新，始終保持最新版本
- 避免 npm 權限問題
終端安裝：
中國大陸用戶網絡問題？
如遇網絡問題，可設置代理後安裝：
或使用 npm 鏡像安裝（需先安裝 Node.js）：
Homebrew 安裝
Homebrew 安裝可能不會自動更新，建議定期運行
brew upgrade claude-code
npm 安裝（備選） 已被官方標記爲棄用
需要 Node.js 18+，適合網絡受限用戶使用國內鏡像
安裝 Node.js
方法一：官網下載（推薦）
打開 https://nodejs.org/，下載 LTS 版本，雙擊安裝。
方法二：Homebrew 安裝
方法三：nvm（多版本管理）
驗證安裝：
全局安裝：
安裝特定版本
安裝穩定版（約延遲一週，跳過重大問題）：
安裝指定版本號：
從 npm 遷移到原生安裝
如果你之前使用 npm 安裝，可以運行遷移命令：
系統會自動處理遷移，然後驗證安裝：
驗證安裝：
提示 .local/bin 不在 PATH 中？
原生安裝後如果提示路徑不在 PATH 中，需要手動添加。編輯 ~/.zshrc（或 ~/.bash_profile）：
在文件末尾添加：
保存後運行 source ~/.zshrc 或重啓終端生效。
這是最關鍵的一步！需要配置 API 代理地址和密鑰。將 sk-xxx 替換爲你的密鑰
之前用過其他中轉服務？先清理舊配置
settings.json 中的 env 優先級高於系統環境變量，需先清理。
檢查配置文件：
檢查環境變量：
清理環境變量（編輯 ~/.zshrc 或 ~/.bash_profile 刪除相關行）：
如果 settings.json 中有 env 包含 ANTHROPIC_BASE_URL，需刪除或修改
方法一：臨時設置（當前終端有效）
方法二：永久配置（推薦）
根據你使用的 shell，編輯對應配置文件（macOS 默認是 zsh）：
添加以下內容：
保存後運行 source ~/.zshrc 或重啓終端生效。
驗證環境變量：
不再使用？刪除環境變量
編輯 ~/.zshrc（或 ~/.bash_profile），刪除相關的 export 行：
刪除以下行：
保存後運行 source ~/.zshrc 或重啓終端生效。
驗證是否刪除成功：
在項目目錄下運行：
首次啓動會進行初始化，稍等片刻即可開始使用。
如果你在 Windows 上使用 WSL，本教程同樣適用。WSL 是 Windows 上運行 Claude Code 的最佳方式，兼容性最好。
安裝 WSL：在 PowerShell（管理員）中運行：
官方推薦的原生安裝方式，無需 Node.js，自動後臺更新，始終保持最新版本。
優點：
- 無需安裝 Node.js 18+
- 自動後臺更新，始終保持最新版本
- 避免 npm 權限問題
中國大陸用戶網絡問題？
如遇網絡問題，可設置代理後安裝：
或使用 npm 鏡像安裝（需先安裝 Node.js）：
npm 安裝（備選） 已被官方標記爲棄用
需要 Node.js 18+，適合網絡受限用戶使用國內鏡像
安裝 Node.js
Ubuntu / Debian：
Fedora / RHEL：
Arch Linux：
驗證安裝：
全局安裝：
安裝特定版本
安裝穩定版（約延遲一週，跳過重大問題）：
安裝指定版本號：
驗證安裝：
這是最關鍵的一步！需要配置 API 代理地址和密鑰。將 sk-xxx 替換爲你的密鑰
方法一：臨時設置（當前終端有效）
方法二：永久配置（推薦）
編輯 ~/.bashrc 或 ~/.zshrc：
添加以下內容：
保存後運行 source ~/.bashrc 或重啓終端生效。
驗證環境變量：
在項目目錄下運行：
首次啓動會進行初始化，稍等片刻即可開始使用。
OpenAI Codex CLI 是 OpenAI 官方推出的命令行 AI 編程助手，類似於 Claude Code，但使用 OpenAI 的模型（如 GPT-4o、o1、o3 等）。
Codex 在 Windows 上推薦使用 WSL（Windows Subsystem for Linux）安裝和運行，兼容性最好。如果不想裝 WSL，至少使用 Git Bash 來運行 Codex。
PowerShell 兼容性較差，可能遇到文件鎖定、寫入失敗（error write file）等問題。遇到問題多問 AI！
Windows Terminal 是微軟官方的現代化終端工具，支持多標籤頁、更好的字符渲染、emoji 和中文顯示。強烈建議用它替代自帶的 cmd 和 PowerShell 窗口。
Microsoft Store 下載 GitHub 下載Codex 需要 Node.js 22+ 環境（注意：不是 18+，必須是 22 或更高版本）。
已安裝？運行 node --version 驗證版本號是否 >= 22。
安裝 Node.js 22+
方法一：官網下載（推薦）
打開 https://nodejs.org/，下載 Current 版本（22.x 或更高），雙擊安裝。
注意：LTS 版本可能是 20.x，請確認下載的是 22+ 版本
方法二：WinGet 安裝
方法三：nvm-windows（多版本管理，推薦）
下載 nvm-setup.exe 從 GitHub Releases
國內加速下載：https://static.yoouu.cn/nvm-setup.exe
驗證安裝：
確保 node 版本號顯示 v22.x.x 或更高
使用 npm 全局安裝：
如遇權限問題，以管理員身份運行 PowerShell
安裝特定版本
安裝指定版本號：
查看所有可用版本：
驗證安裝：
顯示版本號說明安裝成功！
Codex 使用配置文件進行設置。將 sk-xxx 替換爲你的密鑰
之前用過其他中轉服務？先清理舊配置
如果之前配置過其他 Codex 中轉服務，需要先清理舊配置，避免衝突。
檢查現有配置文件：
檢查環境變量：
清理舊環境變量（如有）：
步驟一：設置 API Key 環境變量
按 Win+X → 選擇「終端管理員」或「PowerShell(管理員)」
設置後需重新打開終端生效
步驟二：創建配置文件
配置文件位置：%USERPROFILE%\.codex\config.toml
一鍵寫入命令（覆蓋現有配置）
步驟三：創建 auth.json（重要！）
Codex 還需要 auth.json 文件，用於禁用默認的 OpenAI 認證。
配置文件位置：%USERPROFILE%\.codex\auth.json
一鍵寫入命令：
或手動創建：
粘貼以下內容：
說明：設置爲 null 是爲了禁用默認的 OpenAI 認證，讓 Codex 使用 config.toml 中配置的 env_key（CRS_OAI_KEY 環境變量）來獲取 API 密鑰
手動創建配置文件（已一鍵配置可跳過）
如果已經使用上面的一鍵寫入命令配置成功，可以跳過此步驟。
粘貼以下配置內容：
驗證配置
檢查環境變量：
查看配置文件：
不再使用？刪除配置
刪除環境變量：
刪除配置文件：
在項目目錄下運行：
首次啓動會進行初始化，稍等片刻即可開始使用。
常用啓動參數
指定模型：
全自動模式（自動批准所有操作）：
查看幫助：
Codex 提供三種運行模式，根據你的需求選擇：
suggest 模式（默認，最安全）
默認模式，Codex 只會建議修改，不會自動執行任何操作。
適合：初次使用、重要項目、需要仔細審查每個操作
auto-edit 模式（自動編輯文件）
自動應用文件編輯，但執行命令前仍需確認。
適合：信任 AI 的代碼修改，但想控制命令執行
full-auto 模式（完全自動）
自動執行所有操作，包括文件編輯和命令執行。
注意：此模式下 Codex 會自動執行所有操作，請確保在安全環境中使用！
適合：測試項目、快速原型開發、有版本控制保護的項目
Codex 使用沙箱來限制命令執行的權限，保護你的系統安全：
read-only（只讀模式，默認）
只允許讀取文件，不能寫入或執行危險命令。
最安全的模式，適合代碼審查和分析
workspace-write（工作區寫入）
允許在當前工作目錄內寫入文件，但不能訪問外部目錄。
適合：日常開發，限制在項目目錄內操作
danger-full-access（完全訪問）
允許完全訪問文件系統和執行任意命令。
警告：此模式有安全風險，僅在完全信任的環境中使用！
Codex 支持通過配置文件自定義默認行爲：
配置文件位置
Windows：
macOS/Linux：
配置文件示例
項目級配置（codex.md）
在項目根目錄創建 codex.md 文件，可以爲 Codex 提供項目上下文：
Codex 支持多種 OpenAI 模型：
不同模型的價格和能力不同，請根據需求選擇。
提示 Node.js 版本過低？
Codex 需要 Node.js 22+，如果提示版本過低，請升級 Node.js：
或重新下載安裝最新版 Node.js
連接超時或網絡錯誤？
1. 檢查配置文件是否正確設置
2. 確認 API Key 環境變量是否有效
3. 驗證配置：
權限錯誤？
如果遇到權限相關錯誤，嘗試以管理員身份運行終端，或使用 WSL 環境。
API 返回 401 或 403 錯誤？
1. 檢查 API Key 是否正確
2. 確認 config.toml 中的 base_url 是否正確
3. 驗證環境變量和配置：
命令執行被沙箱阻止？
如果需要執行被阻止的命令，可以調整沙箱模式：
注意：降低沙箱限制會增加安全風險
如何查看 Codex 版本？
如何更新 Codex？
配置文件參數說明
主要配置項：
• model_provider - 模型提供商名稱，對應 [model_providers.xxx] 中的 xxx
• model - 默認使用的模型名稱
• model_reasoning_effort - 推理強度：low/medium/high
• disable_response_storage - 禁用響應存儲
• preferred_auth_method - 認證方式：apikey
• trusted_projects - 信任的項目目錄列表
• trust_level - 信任級別：trusted/untrusted
[model_providers.xxx] 配置：
• name - 提供商名稱
• base_url - API 基礎地址
• wire_api - API 類型：responses/chat
• requires_openai_auth - 是否需要 OpenAI 認證
• env_key - 存儲 API Key 的環境變量名
[features] 配置：
• experimental_windows_sandbox - Windows 沙箱實驗功能
• elevated_windows_sandbox - 提升權限的 Windows 沙箱
• unified_exec - 統一執行
• shell_snapshot - Shell 快照
• powershell_utf8 - PowerShell UTF-8 支持
• steer - 引導功能
如何切換不同的模型？
可以通過命令行參數或修改配置文件來切換模型：
命令行方式：
配置文件方式：
修改 config.toml 中的 model = "xxx" 行
Codex 與 Claude Code 的區別？
Codex (OpenAI)：
• 使用 OpenAI 模型（GPT-4o、o1、o3 等）
• 需要 Node.js 22+
• 使用 config.toml 配置文件
• 支持沙箱模式和多種運行模式
Claude Code (Anthropic)：
• 使用 Anthropic 模型（Claude Sonnet、Opus 等）
• 原生安裝無需 Node.js
• 使用環境變量配置
• 功能更豐富，生態更完善
OpenAI Codex CLI 是 OpenAI 官方推出的命令行 AI 編程助手，類似於 Claude Code，但使用 OpenAI 的模型（如 GPT-4o、o1、o3 等）。
macOS 默認使用 zsh 作爲終端 shell。可以通過 echo $SHELL 查看當前使用的 shell。
推薦使用 iTerm2 或系統自帶的「終端」應用來運行 Codex，體驗更佳。
Codex 需要 Node.js 22+ 環境（注意：不是 18+，必須是 22 或更高版本）。
已安裝？運行 node --version 驗證版本號是否 >= 22。
安裝 Node.js 22+
方法一：官網下載（推薦）
打開 https://nodejs.org/，下載 Current 版本（22.x 或更高），雙擊安裝。
注意：LTS 版本可能是 20.x，請確認下載的是 22+ 版本
方法二：Homebrew 安裝（推薦）
方法三：nvm（多版本管理，推薦）
驗證安裝：
確保 node 版本號顯示 v22.x.x 或更高
使用 npm 全局安裝：
Homebrew 安裝
Homebrew 安裝可能不會自動更新，建議定期運行
brew upgrade openai-codex
安裝特定版本
安裝指定版本號：
查看所有可用版本：
驗證安裝：
顯示版本號說明安裝成功！
Codex 使用配置文件進行設置。將 sk-xxx 替換爲你的密鑰
之前用過其他中轉服務？先清理舊配置
如果之前配置過其他 Codex 中轉服務，需要先清理舊配置，避免衝突。
檢查現有配置文件：
檢查環境變量：
清理舊環境變量（編輯 ~/.zshrc 刪除相關行）：
步驟一：設置 API Key 環境變量
根據你使用的 shell 選擇對應命令。將 sk-xxx 替換爲你的密鑰
提示：運行 echo $SHELL 可查看當前使用的 shell
步驟二：創建配置文件
配置文件位置：~/.codex/config.toml
一鍵寫入命令（覆蓋現有配置）
手動創建配置文件（已一鍵配置可跳過）
如果已經使用上面的一鍵寫入命令配置成功，可以跳過此步驟。
粘貼以下配置內容：
步驟三：創建 auth.json（重要！）
Codex 還需要 auth.json 文件，用於禁用默認的 OpenAI 認證。
配置文件位置：~/.codex/auth.json
一鍵寫入命令：
或手動創建：
粘貼以下內容：
說明：設置爲 null 是爲了禁用默認的 OpenAI 認證，讓 Codex 使用 config.toml 中配置的 env_key（CRS_OAI_KEY 環境變量）來獲取 API 密鑰
驗證配置
檢查環境變量：
查看配置文件：
查看 auth.json：
不再使用？刪除配置
編輯 ~/.zshrc，刪除 export CRS_OAI_KEY=... 行
刪除配置文件：
在項目目錄下運行：
首次啓動會進行初始化，稍等片刻即可開始使用。
常用啓動參數
指定模型：
全自動模式（自動批准所有操作）：
查看幫助：
Codex 提供多種運行模式和沙箱選項：
運行模式（--approval-mode）
沙箱模式（--sandbox）
配置文件
配置文件位置：~/.codex/config.toml
提示 Node.js 版本過低？
Codex 需要 Node.js 22+，如果提示版本過低，請升級 Node.js：
連接超時或網絡錯誤？
1. 檢查配置文件是否正確設置
2. 確認 API Key 環境變量是否有效
3. 驗證配置：
API 返回 401/403 錯誤？
1. 檢查 API Key 是否正確
2. 確認 config.toml 中的 base_url 是否正確
如何更新 Codex？
OpenAI Codex CLI 是 OpenAI 官方推出的命令行 AI 編程助手，類似於 Claude Code，但使用 OpenAI 的模型（如 GPT-4o、o1、o3 等）。
如果你在 Windows 上使用 WSL，本教程同樣適用。WSL 是 Windows 上運行 Codex 的最佳方式，兼容性最好。
安裝 WSL：在 PowerShell（管理員）中運行：
Codex 需要 Node.js 22+ 環境（注意：不是 18+，必須是 22 或更高版本）。
已安裝？運行 node --version 驗證版本號是否 >= 22。
安裝 Node.js 22+
方法一：nvm（推薦，多版本管理）
在終端中執行（按 Ctrl+Alt+T 打開終端）
方法二：包管理器
在終端中執行（按 Ctrl+Alt+T 打開終端）
注意：包管理器安裝的版本可能較舊，如果版本低於 22，請使用方法一（nvm）安裝
方法三：NodeSource 倉庫（指定版本）
驗證安裝：
確保 node 版本號顯示 v22.x.x 或更高
使用 npm 全局安裝：
安裝特定版本
安裝指定版本號：
查看所有可用版本：
權限問題？
如果遇到權限錯誤，可以嘗試以下方法：
方法一：使用 sudo（不推薦）
方法二：修改 npm 全局目錄（推薦）
驗證安裝：
顯示版本號說明安裝成功！
Codex 使用配置文件進行設置。將 sk-xxx 替換爲你的密鑰
之前用過其他中轉服務？先清理舊配置
如果之前配置過其他 Codex 中轉服務，需要先清理舊配置，避免衝突。
檢查現有配置文件：
檢查環境變量：
清理舊環境變量（編輯 ~/.bashrc 或 ~/.zshrc 刪除相關行）：
步驟一：設置 API Key 環境變量
編輯 ~/.bashrc 或 ~/.zshrc：
步驟二：創建配置文件
配置文件位置：~/.codex/config.toml
一鍵寫入命令（覆蓋現有配置）
手動創建配置文件（已一鍵配置可跳過）
如果已經使用上面的一鍵寫入命令配置成功，可以跳過此步驟。
粘貼以下配置內容：
步驟三：創建 auth.json（重要！）
Codex 還需要 auth.json 文件，用於禁用默認的 OpenAI 認證。
配置文件位置：~/.codex/auth.json
一鍵寫入命令：
或手動創建：
粘貼以下內容：
說明：設置爲 null 是爲了禁用默認的 OpenAI 認證，讓 Codex 使用 config.toml 中配置的 env_key（CRS_OAI_KEY 環境變量）來獲取 API 密鑰
驗證配置
檢查環境變量：
查看配置文件：
查看 auth.json：
不再使用？刪除配置
編輯 ~/.bashrc，刪除 export CRS_OAI_KEY=... 行
刪除配置文件：
在項目目錄下運行：
首次啓動會進行初始化，稍等片刻即可開始使用。
常用啓動參數
指定模型：
全自動模式（自動批准所有操作）：
查看幫助：
Codex 提供多種運行模式和沙箱選項：
運行模式（--approval-mode）
沙箱模式（--sandbox）
配置文件
配置文件位置：~/.codex/config.toml
項目級配置（codex.md）
在項目根目錄創建 codex.md 文件，爲 Codex 提供項目上下文：
Codex 支持多種 OpenAI 模型：
提示 Node.js 版本過低？
Codex 需要 Node.js 22+，如果提示版本過低，請升級 Node.js：
連接超時或網絡錯誤？
1. 檢查配置文件是否正確設置
2. 確認 API Key 環境變量是否有效
3. 驗證配置：
WSL 中無法訪問 Windows 文件？
Windows 文件系統掛載在 /mnt/ 目錄下：
建議將項目放在 WSL 文件系統中（如 ~/projects）以獲得更好的性能。
API 返回 401/403 錯誤？
1. 檢查 API Key 是否正確
2. 確認 config.toml 中的 base_url 是否正確
命令被沙箱阻止？
調整沙箱模式：
如何更新 Codex？
配置文件參數說明
主要配置項：
• model_provider - 模型提供商名稱
• model - 默認使用的模型名稱
• model_reasoning_effort - 推理強度：low/medium/high
[model_providers.xxx] 配置：
• base_url - API 基礎地址
• env_key - 存儲 API Key 的環境變量名
• wire_api - API 類型：responses/chat
Codex 與 Claude Code 的區別？
Codex (OpenAI)：
• 使用 OpenAI 模型（GPT-4o、o1、o3 等）
• 需要 Node.js 22+
• 使用 config.toml 配置文件
Claude Code (Anthropic)：
• 使用 Anthropic 模型（Claude Sonnet、Opus 等）
• 原生安裝無需 Node.js
• 使用環境變量配置
Gemini CLI 是 Google 官方推出的命令行 AI 編程助手，使用 Gemini 模型（如 gemini-3-pro-preview 等）。
官方定價參考：https://ai.google.dev/gemini-api/docs/pricing?hl=zh-cn
Windows Terminal 是微軟官方的現代化終端工具，支持多標籤頁、更好的字符渲染、emoji 和中文顯示。強烈建議用它替代自帶的 cmd 和 PowerShell 窗口。
Microsoft Store 下載 GitHub 下載Gemini CLI 需要 Node.js 環境才能運行。
已安裝？運行 node --version 驗證，有版本號可跳過此步驟。
安裝 Node.js
方法一：官網下載（推薦）
打開 https://nodejs.org/，下載 LTS 版本，雙擊安裝。
方法二：nvm-windows（多版本管理）
下載 nvm-setup.exe 從 GitHub Releases
國內加速下載：https://static.yoouu.cn/nvm-setup.exe
方法三：包管理器
驗證安裝：
顯示版本號說明安裝成功！
使用 npm 全局安裝：
如遇權限問題，以管理員身份運行 PowerShell
驗證安裝：
顯示版本號說明安裝成功！
配置連接到中轉服務。將 sk-xxx你的密鑰xxx 替換爲你的密鑰
永久設置（系統級別，需管理員權限）：
按 Win+X → 選擇「終端管理員」或「PowerShell(管理員)」
設置後需重新打開終端生效
驗證環境變量：
不再使用？刪除環境變量
清理系統級環境變量（需管理員）：
在項目目錄下運行：
首次啓動會進行初始化，稍等片刻即可開始使用。
Gemini CLI 是 Google 官方推出的命令行 AI 編程助手，使用 Gemini 模型（如 gemini-3-pro-preview 等）。
官方定價參考：https://ai.google.dev/gemini-api/docs/pricing?hl=zh-cn
macOS 默認使用 zsh 作爲終端 shell。可以通過 echo $SHELL 查看當前使用的 shell。
推薦使用 iTerm2 或系統自帶的「終端」應用來運行 Gemini CLI，體驗更佳。
Gemini CLI 需要 Node.js 環境才能運行。
已安裝？運行 node --version 驗證，有版本號可跳過此步驟。
安裝 Node.js
方法一：官網下載（推薦）
打開 https://nodejs.org/，下載 LTS 版本，雙擊安裝。
方法二：Homebrew 安裝
方法三：nvm（多版本管理）
驗證安裝：
顯示版本號說明安裝成功！
使用 npm 全局安裝：
驗證安裝：
顯示版本號說明安裝成功！
配置連接到中轉服務。將 sk-xxx你的密鑰xxx 替換爲你的密鑰
方法一：臨時設置（當前終端有效）
方法二：永久配置（推薦）
編輯 ~/.zshrc（或 ~/.bash_profile）：
添加以下內容：
保存後運行 source ~/.zshrc 或重啓終端生效。
驗證環境變量：
不再使用？刪除環境變量
編輯 ~/.zshrc，刪除相關的 export 行，然後運行 source ~/.zshrc 或重啓終端生效。
在項目目錄下運行：
首次啓動會進行初始化，稍等片刻即可開始使用。
Gemini CLI 是 Google 官方推出的命令行 AI 編程助手，使用 Gemini 模型（如 gemini-3-pro-preview 等）。
官方定價參考：https://ai.google.dev/gemini-api/docs/pricing?hl=zh-cn
如果你在 Windows 上使用 WSL，本教程同樣適用。WSL 是 Windows 上運行 Gemini CLI 的最佳方式，兼容性最好。
安裝 WSL：在 PowerShell（管理員）中運行：
Gemini CLI 需要 Node.js 環境才能運行。
已安裝？運行 node --version 驗證，有版本號可跳過此步驟。
安裝 Node.js
Ubuntu / Debian：
Fedora / RHEL：
Arch Linux：
驗證安裝：
顯示版本號說明安裝成功！
使用 npm 全局安裝：
驗證安裝：
顯示版本號說明安裝成功！
配置連接到中轉服務。將 sk-xxx你的密鑰xxx 替換爲你的密鑰
方法一：臨時設置（當前終端有效）
方法二：永久配置（推薦）
編輯 ~/.bashrc 或 ~/.zshrc：
添加以下內容：
保存後運行 source ~/.bashrc 或重啓終端生效。
驗證環境變量：
在項目目錄下運行：
首次啓動會進行初始化，稍等片刻即可開始使用。
該產品目前暫未銷售，以下教程僅供參考。如有需要請聯繫站主諮詢。
Droid CLI 是 Factory.ai 推出的命令行 AI 編程助手，支持多種模型（Claude、GPT 等）。
Droid CLI 需要在配置文件中添加自定義模型。將 your_api_key 替換爲你的密鑰
配置文件位置：~/.factory/config.json
編輯配置文件，添加以下內容：
配置完成後，在 Droid CLI 中選擇自定義模型即可使用。
VSCode 和 Cursor 都支持通過插件使用 Claude Code。以下是配置方法。
需要在 .claude 目錄下創建 settings.json 文件。將
sk-XXXX你的key 替換爲你的密鑰
配置文件位置：
Windows: %USERPROFILE%\.claude\settings.json
macOS/Linux: ~/.claude/settings.json
文件內容：
Anthropic 官方提供了 VSCode 插件，可以直接在編輯器中使用 Claude Code。
安裝方式：
1. 打開 VSCode / Cursor
2. 按 Ctrl+Shift+X 打開擴展面板
3. 搜索 "Claude Code" 或 "Anthropic"
4. 點擊安裝
安裝後，插件會自動讀取 settings.json 中的配置，即可使用。
WSL 中運行 Claude Code 最常見的卡頓問題來自：Windows PATH 繼承、跨文件系統訪問慢、Claude 內部調用 PowerShell 的 bug。以下配置可以顯著提升流暢度。
禁用 Windows 路徑互操作：
在 WSL 終端中執行（按 Ctrl+Alt+T 打開終端）
緩存 USERPROFILE 避免 PowerShell 調用：
Claude Code 輸出長內容時，Windows Terminal 默認的 9001 行歷史記錄容易溢出，導致滾動條跳回頂部。將 historySize 設爲最大值 32767 可顯著改善。
方法一：圖形界面設置
1. 打開 Windows Terminal → 下拉箭頭 → 設置
2. 左側選擇 配置文件 → 默認值
3. 找到 高級 → 歷史記錄大小，改爲 32767
4. 點擊 保存，重啓 Windows Terminal
方法二：一鍵配置（推薦）
在 PowerShell 中執行以下命令自動配置 settings.json：
配置完成後需要執行 wsl --shutdown 重啓 WSL 使配置生效。
CC-Switch 是一個圖形化配置管理工具，可以幫助你快速切換多個 Claude Code / Codex / Gemini 配置，無需手動修改環境變量。
提示：如果配置後環境變量仍不生效，請先卸載 CC-Switch，重新安裝後再次配置。若問題依舊，請聯繫站主協助處理。
下載安裝後，右鍵點擊 CC-Switch 圖標 → 屬性 → 兼容性 → 勾選「以管理員身份運行此程序」
支持管理多個配置，一鍵切換不同的 API 供應商：
點擊右上角 + 號添加新配置，填入供應商名稱、API Key 和請求地址即可：
狀態欄插件可以在終端顯示模型信息、Git 分支、Token 使用量、會話成本等實時指標。以下是幾款流行的狀態欄插件，選擇適合你的使用。
CCometixLine 是用 Rust 編寫的高性能 Claude Code 狀態欄工具，相比 Node.js 實現更輕量、啓動更快。支持實時使用追蹤、Git 集成、交互式 TUI 配置界面。
- Rust 編寫，性能更高、內存佔用更低
- 實時 Token 使用追蹤和成本計算
- Git 分支和狀態集成
- 交互式 TUI 配置界面
安裝：
配置：
配置文件位置：~/.claude/ccline/config.toml
添加到 Claude Code（Linux/macOS）：
添加到 Claude Code（Windows）：
較早的狀態欄插件，功能基礎但穩定。使用 Node.js 編寫。
安裝：
添加到 Claude Code：
類似 Powerline 風格的狀態欄插件，界面美觀。
安裝：
添加到 Claude Code：
輕量級狀態欄插件，簡潔實用。
安裝：
添加到 Claude Code：
社區維護的狀態欄插件，功能完善。
安裝：
添加到 Claude Code：
opencode 是一個開源的 AI 編程助手 CLI 工具，支持通過配置文件自定義 provider 連接中轉服務。
注意：目前文檔只是作爲一個示例，opencode 非常不好用，你自己根據示例折騰，文檔不一定正確。
全局配置：~/.config/opencode/opencode.json
Windows: %USERPROFILE%\.config\opencode\opencode.json
項目配置：./opencode.json
項目配置優先級高於全局配置
在配置目錄安裝對應的 SDK 包：
選擇分組類型：
在配置文件中添加以下內容：將 your-claude_code-key 替換爲你的密鑰
安裝依賴：npm install @ai-sdk/anthropic
在配置文件中添加以下內容：將 your-gemini-key 替換爲你的密鑰
安裝依賴：npm install @ai-sdk/google
在配置文件中添加以下內容：將 your-codex-key 替換爲你的密鑰
安裝依賴：npm install @ai-sdk/openai
安裝 opencode 並啓動：
everything-claude-code 是來自 Anthropic 黑客松獲獎者的配置集合，包含精心設計的 agents、skills、commands、rules、hooks 和 MCP 配置，可以顯著提升 Claude Code 的使用體驗。
| Agents | planner、architect、code-reviewer 等 9 個專業代理 |
| Skills | 編碼標準、後端/前端模式、TDD 方法論等 |
| Commands | /tdd、/plan、/e2e、/code-review 等 10 個命令 |
| Rules | 安全、編碼風格、測試、git 工作流規則 |
| Hooks | PreToolUse、PostToolUse、Stop 事件觸發器 |
| MCP Configs | GitHub、Supabase、Vercel 等服務配置 |
方法一：插件安裝（推薦）
使用 Claude Code 內置的插件系統一鍵安裝：
方法二：手動安裝（Windows PowerShell）
手動克隆倉庫並複製配置文件：
方法二：手動安裝（macOS/Linux）
手動克隆倉庫並複製配置文件：
以下是針對全棧和 JavaScript 開發者的推薦配置組合：
Agents：
| planner.md | 功能規劃，拆解任務 |
| architect.md | 系統設計決策 |
| code-reviewer.md | 代碼質量審查 |
| build-error-resolver.md | 構建錯誤修復 |
| e2e-runner.md | E2E 測試 |
Commands：
| /plan | 實現規劃 |
| /code-review | 質量審查 |
| /build-fix | 修復構建錯誤 |
| /e2e | E2E 測試 |
Skills：
| coding-standards | 語言最佳實踐 |
| backend-patterns | API、數據庫模式 |
| frontend-patterns | React、Next.js 模式 |
以後更新只需拉取最新代碼，然後重新複製需要的文件：
然後重新複製需要的文件
- 每個項目啓用的 MCP 不要超過 10 個，活躍工具不超過 80 個
- 200k 上下文窗口可能因工具過多縮減至 70k
- 配置中的 YOUR_*_HERE 佔位符需要替換爲實際 API 密鑰
MCP (Model Context Protocol) 是 Anthropic 推出的開放協議，讓 Claude Code 能夠連接外部工具和數據源，大幅擴展 AI 的能力邊界。
MCP 讓 Claude Code 能夠：
- 訪問最新的庫和框架文檔（如 Context7）
- 操作 GitHub、Notion、Figma 等外部服務
- 執行瀏覽器自動化、數據庫查詢等任務
- 連接 Zapier 等自動化平臺實現跨應用工作流
MCP 配置存儲在 JSON 文件中，支持全局和項目級別配置：
| 全局 (macOS/Linux) | ~/.claude/mcp.json |
| 全局 (Windows) | %USERPROFILE%\.claude\mcp.json |
| 項目級別 | .claude/mcp.json |
方式一：命令行安裝（推薦）
使用 Claude Code 內置命令管理 MCP 服務器：
方式二：手動配置
直接編輯 ~/.claude/mcp.json 文件：
以下是社區推薦的常用 MCP 服務器：
Context7 - 獲取最新的庫和框架文檔、API 信息、代碼示例 需要 API Key
GitHub - 訪問 GitHub 倉庫、Issue、PR，支持代碼搜索和文件操作 需要 API Key
Playwright - 瀏覽器自動化和網頁抓取，支持截圖、表單填寫、數據提取
Puppeteer - 無頭瀏覽器控制、網頁抓取、PDF 生成、表單自動化
Docker - 容器生命週期管理、鏡像構建、Docker Compose 編排
Sequential Thinking - 鏈式思維推理、逐步問題解決、複雜任務分析
Notion - 訪問和管理 Notion 工作區、搜索頁面、創建筆記、更新數據庫 需要 API Key
Slack - 讀取和發送消息、搜索頻道和用戶、文件共享、線程管理 需要 API Key
Linear - 創建和更新 Issue、項目查詢、Sprint 規劃、狀態跟蹤 需要 API Key
Figma - 訪問設計文件、導出資源、分析設計系統、組件分析 需要 API Key
Supabase - PostgreSQL 數據庫訪問、身份驗證、存儲和文件操作 需要 API Key
PostgreSQL - SQL 查詢執行、模式檢查、連接池、只讀模式
SQLite - 輕量級數據庫操作、本地數據存儲
Zapier - 連接 5000+ 應用、Zap 創建和管理、工作流自動化 需要 API Key
Filesystem - 本地文件讀寫、目錄操作
Context7 是最受歡迎的 MCP 服務器之一，可以讓 Claude Code 訪問最新的庫和框架文檔，避免使用過時的 API。
安裝方式一：遠程連接（推薦，全局可用）
安裝方式二：本地運行
使用方法 - 在提示詞中加入 use context7 即可讓 Claude Code 查詢最新文檔：
- 每個項目啓用的 MCP 不要超過 10 個，活躍工具不超過 80 個
- 200k 上下文窗口可能因工具過多縮減至 70k
- 需要 API Key 的服務器請替換 YOUR_API_KEY 爲實際密鑰
- 部分 MCP 服務器需要額外安裝依賴，請參考各自的官方文檔
CLAUDE.md 支持全局和項目級別配置，項目級配置優先級更高：
| 全局 (macOS/Linux) | ~/.claude/CLAUDE.md |
| 全局 (Windows) | %USERPROFILE%\.claude\CLAUDE.md |
| 項目級別 | .claude/CLAUDE.md |
以下是一個完整的 CLAUDE.md 配置示例，包含版本標識、工作流程、編碼規範等：
複製後粘貼到對應路徑的 CLAUDE.md 文件中，根據你的需求修改內容即可。
- 版本標識規範可以幫助你確認規則是否生效
- CRITICAL CONSTRAINTS 定義了必須遵守的約束
- MANDATORY WORKFLOWS 定義了工作流程
- SUBAGENT SELECTION 定義了子代理選擇策略
- 項目特定配置可以根據你的項目需求自定義
OpenClaw（原 Clawdbot/Moltbot）是一個開源的個人 AI 助手系統，支持多種消息渠道（WhatsApp、Telegram、Discord 等）和多個 AI 模型提供商。通過配置自定義 provider 可以連接中轉服務。
Node.js >= 22，支持 Windows 原生或 WSL2
官方推薦使用 WSL2，但原生 Windows 也可以使用。
Node.js 安裝教程
已安裝 Node.js？運行 node --version 驗證，有版本號可跳過此步驟
方法一：官網下載（推薦）
打開 https://nodejs.org/，下載 LTS 版本，雙擊安裝。
方法二：nvm-windows（多版本管理）
下載 nvm-setup.exe 從 GitHub Releases
方法三：包管理器
驗證安裝：
使用 npm 全局安裝 OpenClaw：
編輯配置文件，添加自定義 provider 連接中轉服務：
配置文件位置：C:\Users\用戶名\.openclaw\openclaw.json
打開配置文件（PowerShell）：
Node.js >= 22，支持 macOS
Node.js 安裝教程
已安裝 Node.js？運行 node --version 驗證，有版本號可跳過此步驟
方法一：Homebrew（推薦）
方法二：nvm（多版本管理）
國內下載慢？點擊查看加速安裝方式
驗證安裝：
使用 npm 全局安裝 OpenClaw：
編輯配置文件，添加自定義 provider 連接中轉服務：
配置文件位置：~/.openclaw/openclaw.json
打開配置文件（終端）：
Node.js >= 22，支持 Linux / WSL
Node.js 安裝教程
已安裝 Node.js？運行 node --version 驗證，有版本號可跳過此步驟
方法一：nvm（推薦）
國內下載慢？點擊查看加速安裝方式
方法二：包管理器
驗證安裝：
使用 npm 全局安裝 OpenClaw：
編輯配置文件，添加自定義 provider 連接中轉服務：
配置文件位置：~/.openclaw/openclaw.json
打開配置文件（終端）：
運行初始化嚮導完成基本配置：
嚮導選項說明：
| Security 安全確認 | Yes |
| Onboarding mode | Manual (手動配置) |
| What do you want to set up? | Local gateway (this machine) |
| Model/auth provider | Skip for now 或 Back |
| Gateway port | 18789 (默認) |
| Gateway bind | LAN (0.0.0.0) |
| Gateway auth | Token |
| Tailscale exposure | Off (除非需要遠程訪問) |
| Configure chat channels now? | No (先跳過) |
| Set GOOGLE_PLACES_API_KEY? | No |
| Configure skills now? | No 或 Skip for now |
嚮導完成後會自動安裝 Gateway 後臺服務。如果提示 "Model check: No auth configured"，這是正常的，後面會手動配置中轉服務。
| macOS / Linux | ~/.openclaw/openclaw.json |
| Windows | C:\Users\用戶名\.openclaw\openclaw.json |
將 sk-xxx你的密鑰xxx 替換爲你的密鑰
配置完成後，運行以下命令驗證：
如果 models list 顯示你配置的模型且 Auth 爲 yes，說明配置成功！
啓動 Gateway 服務並開始使用：
| openclaw gateway | 前臺啓動 Gateway 服務 |
| openclaw gateway --verbose | 前臺啓動並顯示詳細日誌 |
| openclaw gateway install | 安裝 Gateway 後臺服務 |
| openclaw gateway start | 啓動後臺服務 |
| openclaw gateway stop | 停止後臺服務 |
| openclaw tui | 啓動 TUI 交互界面 |
| openclaw models list | 查看已配置的模型 |
| openclaw doctor | 檢查配置問題 |
| openclaw doctor --fix | 自動修復配置問題 |
| openclaw plugins enable telegram | 啓用 Telegram 插件 |
baseUrl 格式錯誤（最常見）
- 正確 "baseUrl": "https://xxx.xxx.xxx"
- 錯誤 "baseUrl": "https://xxx.xxx.xxx/" (末尾多了斜槓)
- 錯誤 "baseUrl": "https://xxx.xxx.xxx/api" (多了 /api)
- 錯誤 "baseUrl": "https://xxx.xxx.xxx/v1" (路徑錯誤)
gateway.mode 未設置
必須設置 gateway.mode，否則會報錯 "Gateway start blocked"
模型格式錯誤
- 正確 "primary": "nexus/claude-opus-4-6"
- 錯誤 "primary": "claude-opus-4-6"
| No API key found | 檢查 apiKey 配置是否正確 |
| Gateway start blocked | 添加 "mode": "local" 到 gateway 配置 |
| Connection refused | 檢查 baseUrl 和網絡連接 |
| 401 Unauthorized | 檢查 apiKey 是否正確 |
| 404 Not Found | 檢查 baseUrl 路徑是否正確 |
配置 Telegram
OpenClaw 需要配置一個對話界面來使用，目前暫不支持微信。以下以 Telegram 爲例：
1. 獲取 Telegram Bot Token
- 在 Telegram 中搜索 @BotFather
- 發送 /newbot
- 按提示設置 bot 名稱
- 獲得 Bot Token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）
2. 啓用 Telegram 插件
3. 配置 Bot Token
4. 啓動 Gateway
5. 配對驗證
- 在 Telegram 中找到你的 bot，發送任意消息
- Bot 會返回一個驗證碼
- 在終端執行：
完成配對後即可在 Telegram 中與 AI 對話！
安裝和使用過程中常見問題的解決方案。
安裝時提示 "permission denied"
以管理員身份運行 PowerShell，或配置 npm 使用用戶目錄：
PowerShell 執行策略錯誤
運行以下命令解除限制：
環境變量設置後不生效
重新打開 PowerShell 或註銷重新登錄。
Git 版本過舊導致中文路徑報錯
Git 2.24.0 及更早版本（2019年）的 cygpath.exe 無法正確處理 UTF-8/Unicode 字符，會導致 Claude Code 在中文目錄下報錯。建議升級到 Git 2.40+ 版本。
方案一：升級 Git（推薦）
方案二：使用 Windows 短路徑繞過中文
在 PowerShell 中獲取短路徑，然後用短路徑進入目錄啓動 Claude Code：
方案三：創建英文符號鏈接
以管理員身份運行終端，創建英文路徑指向中文路徑：