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
验证安装：
显示版本号说明安装成功！
配置连接到中转服务。将 cr_xxxxxxxxxx 替换为你的密钥
永久设置（系统级别，需管理员权限）：
按 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 全局安装：
验证安装：
显示版本号说明安装成功！
配置连接到中转服务。将 cr_xxxxxxxxxx 替换为你的密钥
方法一：临时设置（当前终端有效）
方法二：永久配置（推荐）
编辑 ~/.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 全局安装：
验证安装：
显示版本号说明安装成功！
配置连接到中转服务。将 cr_xxxxxxxxxx 替换为你的密钥
方法一：临时设置（当前终端有效）
方法二：永久配置（推荐）
编辑 ~/.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：
方案三：创建英文符号链接
以管理员身份运行终端，创建英文路径指向中文路径：