Claude Code 等 AI Agent 工具零基础部署指南

适用于 Windows、macOS、Linux 新手用户

本文面向零基础新手，手把手介绍如何在 Windows、macOS、Linux 三大操作系统中安装和配置 Claude Code、Codex、Hermes 等 AI Agent 工具。

通过本文，你将完成以下内容：

• 安装 Node.js、Git、Python 等基础开发环境

• 安装并配置 Claude Code

• 配置国内大模型 API

• 安装 VS Code、Chrome 等常用工具

• 解决 GitHub 访问问题

• 在 Windows 上配置 WSL 子系统

• 在不同系统中使用 AI Agent 工具辅助开发

一、Windows 系统部署指南

1. 安装 Node.js

Node.js 是运行 Claude Code、Codex、OpenCloud 等大量 AI Agent 软件所必需的运行环境。

请前往 Node.js 官网，下载 Windows 系统安装程序。

安装方式很简单：

1. 打开安装包

2. 一路点击“下一步”

3. 等待安装完成

安装完成后，打开终端，输入以下命令验证是否安装成功：

node -vnpm -v

如果能够正常打印版本号，说明 Node.js 安装成功。

2. 安装 Git

Git 是全球最流行的版本控制工具，可以帮助你管理代码版本，随时回退到历史节点。

请前往 Git 官网 下载 Windows 安装包。

一般情况下，普通电脑选择 X86 64 位版本 即可。

安装方式：

1. 打开安装包

2. 一路点击“下一步”

3. 安装完成后打开终端

输入以下命令验证：

git --version

如果能够看到 Git 版本号，说明安装成功。

3. 安装与配置 Claude Code

在桌面空白处右键，选择打开终端，然后输入 Claude Code 的安装命令：

# 此处粘贴 Claude Code 官方安装命令

安装完成后，需要配置 Claude Code 使用的大模型服务。

4. 配置国内大模型 API

打开以下目录：

C:用户你的用户名

或者：

C:Users你的用户名

然后进行以下操作：

1. 点击顶部菜单中的“查看”

2. 勾选“显示隐藏文件夹”

3. 勾选“文件扩展名”

4. 在当前目录右键新建一个文本文档

5. 将文件重命名为：

.claude.json

用记事本打开 .claude.json 文件，粘贴 Claude Code 的基础配置内容。

你通常需要修改两处内容：

• token：也就是 API Key，可以在国内大模型厂商控制台创建并复制

• baseUrl：模型厂商提供的 API 地址，可以在厂商 API 文档中找到

示例结构如下：

{ "token": "你的 API Key", "baseUrl": "模型厂商的 API 地址"}

保存配置文件后，在终端输入：

claude

首次启动时，根据提示选择信任当前文件夹。

如果 Claude 能正常回复打招呼的信息，就说明配置成功。

5. 安装 VS Code 代码编辑器

VS Code 是轻量、强大且非常适合新手使用的代码编辑器。

请前往 VS Code 官网 下载 Windows 安装程序。

安装方式：

1. 打开安装包

2. 一路点击“下一步”

3. 安装完成后启动 VS Code

后续可以在 VS Code 中打开项目，并配合 Claude Code、Codex 等 Agent 工具进行开发。

6. 解决 GitHub 网络访问问题

国内直接访问 GitHub 时，可能会出现访问慢、加载失败、超时等问题。

可以使用微软系统自带的 Microsoft Store 安装免费开源软件：

Watt Toolkit

操作步骤：

1. 打开 Microsoft Store

2. 搜索 Watt Toolkit

3. 安装并打开软件

4. 找到“网络加速”

5. 勾选 GitHub

6. 点击“一键启动加速”

启动后，即可更顺畅地访问 GitHub，并完成账号注册、代码下载等操作。

7. 安装 Python 与虚拟环境

请前往 Python 官网 下载 Windows 安装器。

安装时注意勾选：

Add Python to PATH

然后点击安装。

安装完成后，打开终端，输入：

python --version

如果能正常显示版本号，说明 Python 安装成功。

8. 推荐使用 Python 虚拟环境

为了防止不同项目之间的依赖互相冲突，强烈建议每个项目都使用独立的 Python 虚拟环境。

进入项目目录后，执行：

python -m venv .venv

激活虚拟环境：

.venvScriptsactivate

激活成功后，再使用 pip 安装依赖：

pip install 包名

你也可以在向 AI Agent 下达任务时明确说明：

请必须使用 Python 虚拟环境，不要全局安装依赖。

这样可以避免污染系统环境。

9. 配置 WSL Linux 子系统

部分 AI Agent 工具在原生 Windows 上兼容性不佳，例如 Hermes 等工具，通常需要借助 Linux 环境运行。

Windows 可以通过 WSL 安装 Linux 子系统。

操作步骤：

1. 在 Windows 搜索栏搜索“功能”

2. 打开“启用或关闭 Windows 功能”

3. 勾选以下两项：

适用于 Linux 的 Windows 子系统虚拟机平台

4. 重启电脑

重启后，打开终端，输入：

wsl --install --download

等待下载安装完成。

安装完成后，系统会要求你设置 Linux 用户名和密码。

验证 WSL 是否安装成功：

wsl --list

默认情况下，系统通常会安装 Ubuntu。

10. Windows 与 WSL 文件互通

WSL 中的 Linux 系统可以和 Windows 文件互通。

在 Windows 资源管理器左侧，可以看到 Linux 图标，点击即可访问 Linux 文件。

在 WSL 终端中，也可以通过以下命令访问 Windows 的 C 盘：

cd /mnt/c/

例如进入 Windows 用户目录：

cd /mnt/c/Users/你的用户名

11. 在 WSL 中安装 Hermes Agent

打开 WSL 终端，粘贴 Hermes Agent 的一键安装命令：

# 此处粘贴 Hermes 官方一键安装命令

如果安装过程中网络失败，可以多尝试几次。

安装完成后，根据提示选择模型提供商。

常见选择：

OpenRouter

然后前往 OpenRouter 网站创建 API Key，复制后粘贴到终端中。

如果只是体验，可以优先选择免费模型开始测试。

12. 安装 Codex

Codex 对国内用户相对友好，额度也较高，但通常需要具备可访问外网的网络环境，并且需要 ChatGPT Plus 订阅。

在终端输入 Codex 安装命令：

# 此处粘贴 Codex 官方安装命令

启动后，浏览器会自动弹出登录页面。

登录你的 ChatGPT 账户后，即可完成授权。

二、macOS 苹果电脑部署指南

1. 更换浏览器

不建议使用 Mac 自带的 Safari 浏览器作为主要开发浏览器。

建议先安装 Chrome。

操作步骤：

1. 使用百度搜索进入 Chrome 官网

2. 下载 macOS 安装包

3. 双击打开 .dmg 文件

4. 将 Chrome 拖拽到 Applications 文件夹中

安装完成后，在“应用程序”中启动 Chrome。

2. 安装命令行工具包

打开 Mac 的“终端”，输入：

xcode-select --install

系统会弹出安装提示，点击同意并等待安装完成。

该工具包会自动安装 Git 等基础开发工具。

验证 Git 是否安装成功：

git --version

如果能看到版本号，说明安装成功。

3. 正确安装 Node.js

重要避坑提醒

macOS 上不建议直接去 Node.js 官网下载安装包。

原因是这种方式可能会把 Node.js 安装到系统目录，后续容易出现权限问题，例如：

permission deniedEACCES需要 sudo 才能安装 npm 包

推荐使用 NVM 来安装和管理 Node.js。

4. 安装 NVM

在终端中依次执行 NVM 的安装命令：

# 此处粘贴 NVM 官方安装命令

安装完成后，重新加载终端配置：

source ~/.zshrc

如果你的系统使用的是 bash，则执行：

source ~/.bashrc

5. 使用 NVM 安装 Node.js

例如安装 Node.js 24 版本：

nvm install 24

使用该版本：

nvm use 24

验证安装结果：

node -vnpm -v

如果能正常显示版本号，说明 Node.js 安装完成。

6. 安装与配置 Claude Code

在终端中输入 Claude Code 安装命令：

# 此处粘贴 Claude Code 官方安装命令

然后进入用户主目录：

cd ~

创建 Claude Code 配置文件：

touch .claude.json

7. 编辑 Claude Code 配置文件

打开 Finder，也就是“访达”。

进入用户主目录后，按下快捷键显示隐藏文件：

Command + Shift + .

找到 .claude.json 文件并打开。

粘贴配置内容，并修改以下两项：

• token：你的 API Key

• baseUrl：模型厂商 API 地址

示例结构：

{ "token": "你的 API Key", "baseUrl": "模型厂商的 API 地址"}

保存后回到终端，输入：

claude

根据提示完成授权。

如果 Claude 能正常回复，说明配置成功。

8. 解决 GitHub 访问问题

可以下载 Mac 版的 Watt Toolkit。

操作步骤：

1. 下载 Mac 版 Watt Toolkit 压缩包

2. 解压后拖拽到 Applications 文件夹

3. 如果无法打开，进入：

系统设置 -> 隐私与安全性

4. 点击“仍要打开”

5. 打开软件后勾选 GitHub

6. 点击“一键加速”

如果遇到权限报错，根据软件提示在终端执行授权命令即可。

9. 安装 Homebrew

Homebrew 是 macOS 上非常重要的软件包管理工具。

解决 GitHub 网络问题后，前往 Homebrew 官网，复制官方一键安装命令。

在终端中粘贴执行：

# 此处粘贴 Homebrew 官方安装命令

安装完成后，按终端提示配置环境变量。

验证是否安装成功：

brew -v

10. 安装 Python

使用 Homebrew 安装 Python 3.12：

brew install python@3.12

安装完成后，可以查看版本：

python3.12 --version

11. 配置 Python 命令别名

打开主目录下的 .zshrc 文件：

open ~/.zshrc

在文件末尾添加：

alias python="python3.12"alias python3="python3.12"alias pip="pip3.12"alias pip3="pip3.12"

保存后执行：

source ~/.zshrc

验证：

python --versionpip --version

12. macOS 上必须使用 Python 虚拟环境

Homebrew 默认不推荐也不允许随意全局安装 Python 依赖。

因此在 Mac 上开发时，建议每个项目都创建独立虚拟环境。

进入项目目录：

cd 你的项目目录

创建虚拟环境：

python -m venv .venv

激活虚拟环境：

source .venv/bin/activate

激活后再安装依赖：

pip install 包名

这样可以避免不同项目之间的依赖互相冲突。

三、Linux 系统部署指南

以 Ubuntu 24.04 为例

Linux 系统的部署相对最快，大多数操作都可以通过终端完成。

1. 更新 APT 软件索引

在桌面右键打开终端，输入：

sudo apt update

系统会要求输入电脑密码。

注意：输入密码时终端不会显示内容，这是正常现象。

2. 安装必备工具

安装 curl：

sudo apt install curl

安装过程中如果提示确认，输入：

Y

然后回车。

安装 Git：

sudo apt install git

验证 Git 是否安装成功：

git --version

3. 安装 Node.js

Linux 上也强烈推荐使用 NVM 安装 Node.js。

不要直接使用系统自带的旧版本 Node.js，否则可能导致部分 Agent 工具无法正常运行。

执行 NVM 安装命令：

# 此处粘贴 NVM 官方安装命令

安装完成后，重新加载终端配置：

source ~/.bashrc

如果你使用的是 zsh，则执行：

source ~/.zshrc

安装 Node.js：

nvm install 24

使用 Node.js 24：

nvm use 24

验证：

node -vnpm -v

4. 安装与配置 Claude Code

在终端输入 Claude Code 安装命令：

# 此处粘贴 Claude Code 官方安装命令

进入用户主目录：

cd /home/你的用户名

也可以使用简写：

cd ~

创建配置文件：

touch .claude.json

5. 编辑 Claude Code 配置

打开文件管理器，点击左上角菜单，选择：

显示隐藏文件

找到 .claude.json 文件，双击打开。

粘贴配置内容，并修改以下两项：

• token：你的 API Key

• baseUrl：模型厂商 API 地址

示例：

{ "token": "你的 API Key", "baseUrl": "模型厂商的 API 地址"}

保存后回到终端，输入：

claude

如果 Claude 正常启动并返回消息，说明配置成功。

6. 安装 VS Code

前往 VS Code 官网，下载 Linux 版本安装包。

Ubuntu 推荐下载 .deb 格式。

下载完成后，进入下载目录：

cd ~/Downloads

安装：

sudo apt install ./安装包名称.deb

例如：

sudo apt install ./code_版本号_amd64.deb

安装完成后，可以在应用程序列表中找到 VS Code。

7. 安装 Chrome

前往 Chrome 官网或 Chrome 国内下载页面，下载 Linux 版本 .deb 安装包。

进入下载目录：

cd ~/Downloads

安装 Chrome：

sudo apt install ./安装包名称.deb

例如：

sudo apt install ./google-chrome-stable_current_amd64.deb

安装完成后，可以在应用程序列表中找到 Chrome。

四、通用建议

1. 优先使用虚拟环境

无论是 Windows、macOS 还是 Linux，只要涉及 Python 项目，都建议使用虚拟环境。

创建虚拟环境：

python -m venv .venv

Windows 激活方式：

.venvScriptsactivate

macOS / Linux 激活方式：

source .venv/bin/activate

2. 不要随意全局安装依赖

如果 AI Agent 要求你执行类似命令：

pip install xxx

建议先确认当前是否已经进入虚拟环境。

如果命令行前面出现类似：

(.venv)

说明已经进入虚拟环境。

3. 给 AI Agent 下任务时要说清楚环境要求

例如：

请在当前项目中创建 Python 虚拟环境，并且所有依赖都必须安装到虚拟环境中，不允许全局安装。

或者：

请先检查当前系统环境，再给出适合 Windows 的命令，不要直接给 Linux 命令。

这样可以减少 Agent 给错命令的概率。

4. 常用验证命令汇总

查看 Node.js 版本：

node -v

查看 npm 版本：

npm -v

查看 Git 版本：

git --version

查看 Python 版本：

python --version

或者：

python3 --version

查看当前目录：

pwd

查看当前文件列表：

ls

Windows 中查看当前目录：

cd

五、总结

对于新手来说，部署 AI Agent 工具的核心并不复杂，主要分为以下几步：

1. 安装基础运行环境：Node.js、Git、Python

2. 安装代码编辑器：VS Code

3. 配置 AI Agent 工具：如 Claude Code、Codex、Hermes

4. 配置模型 API：填写 token 和 baseUrl

5. 解决网络访问问题：尤其是 GitHub

6. 使用虚拟环境隔离项目依赖

7. 遇到 Windows 兼容性问题时，优先考虑使用 WSL

如果你是完全零基础用户，建议优先从 Windows 或 macOS 开始，先跑通 Claude Code，再逐步尝试 Codex、Hermes 等其他 Agent 工具。

最终目标不是一次性掌握所有命令，而是先把环境搭起来，让 AI Agent 真正参与到你的开发流程中。