Claude Code 研学宝典：04 Windows / Linux 部署 Claude Code

基于 AIOAGI 平台的Claude Code安装、配置与验证教程

本文仅保留两条部署主线：Windows 使用 PowerShell，Linux 使用 Bash。请直接进入与你的操作系统对应的章节执行，不需要混用两套命令。

⚠️ 关键的配置

AIOAGI Base URL 统一填写 **https://api.aiearth.dev/**，末尾不要添加 /v1；实际 Messages API 请求路径为 https://api.aiearth.dev/v1/messages。模型名称请以 AIOAGI 控制台当前显示的可用模型 ID 为准。

一、开始前准备

开始安装前，请确认以下条件已经具备：

• AIOAGI 账号；

• 已在 AIOAGI「令牌管理」中创建 API Key；

• API Key 所属 Token 分组有可用额度；

• 该 Token 分组支持你准备使用的 Claude 模型；

• 准备一个用于验证的代码项目。

配置项速览

配置项	填写内容
ANTHROPIC_BASE_URL	https://api.aiearth.dev/
ANTHROPIC_AUTH_TOKEN	AIOAGI API Key
ANTHROPIC_MODEL	AIOAGI 控制台中当前 Token 分组实际可用的模型 ID
API_TIMEOUT_MS	可选；示例值 3000000，单位为毫秒

二、Windows：PowerShell 主线

2.1 安装 Claude Code

打开 PowerShell，执行 Anthropic 官方 Native Install：

irm https://claude.ai/install.ps1 | iex

安装完成后，关闭并重新打开 PowerShell，然后验证：

claude --version

Windows 原生安装通常不需要管理员权限。如果仍提示找不到命令，可继续检查：

Get-Command claude

2.2 创建用户级 settings.json

在 PowerShell 中创建 Claude Code 用户配置目录，并打开 settings.json：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude" | Out-Null

notepad "$env:USERPROFILE\.claude\settings.json"

写入以下配置，并将占位符替换为你的 AIOAGI API Key 和模型 ID：

{

"env": {

"API_TIMEOUT_MS": "3000000",

"ANTHROPIC_BASE_URL": "https://api.aiearth.dev/",

"ANTHROPIC_AUTH_TOKEN": "<YOUR_AIOAGI_API_KEY>",

"ANTHROPIC_MODEL": "<YOUR_MODEL_ID>"

}

}

各字段含义：

• ANTHROPIC_BASE_URL：固定填写 https://api.aiearth.dev/，不要添加 /v1。

• ANTHROPIC_AUTH_TOKEN：填写 AIOAGI API Key。

• ANTHROPIC_MODEL：填写 AIOAGI 控制台中该 Token 分组实际可用的模型 ID。

• API_TIMEOUT_MS：可选超时设置，单位为毫秒；网络较慢或模型响应较长时可以保留。

• 不要额外添加顶层 "model"；本教程只使用 ANTHROPIC_MODEL 作为模型配置来源。

2.3 验证 Windows CLI

进入一个用于测试的项目目录：

Set-Location C:\path\to\your-project

claude doctor

claude

进入 Claude Code 后先执行：

/status

确认地址、模型和配置来源正确后，再发送一个低风险请求，例如：

请先阅读当前仓库结构，再总结主要目录和入口文件，不要修改文件。

2.4 验证 VS Code 官方扩展

如果你使用 Claude Code 官方 VS Code 扩展，建议在 VS Code 的用户设置 JSON 中显式配置扩展环境变量。打开命令面板，选择 Preferences: Open User Settings (JSON)，然后在现有 JSON 中合并以下属性：

{

"claudeCode.environmentVariables": [

{

"name": "ANTHROPIC_BASE_URL",

"value": "https://api.aiearth.dev/"

},

{

"name": "ANTHROPIC_AUTH_TOKEN",

"value": "<YOUR_AIOAGI_API_KEY>"

},

{

"name": "ANTHROPIC_MODEL",

"value": "<YOUR_MODEL_ID>"

}

]

}

替换占位符后重新加载 VS Code 窗口，并在扩展终端或 Claude Code 面板中执行 /status 进行验证。

2.5 可选：PowerShell 直连 AIOAGI API 测试

只有在 CLI 或 VS Code 扩展报错时才需要做这一步。它用于区分"API Key / 模型 / 网络"问题和"Claude Code 配置"问题。测试请求直接访问 /v1/messages，不会修改项目文件。

$baseUrl = "https://api.aiearth.dev"

$apiKey = Read-Host "输入 AIOAGI API Key"

$model = Read-Host "输入 AIOAGI 模型 ID"

$headers = @{

"Authorization" = "Bearer $apiKey"

"anthropic-version" = "2023-06-01"

"Content-Type" = "application/json"

}

$body = @{

model = $model

max_tokens = 32

messages = @(

@{

role = "user"

content = "Reply with OK only."

}

)

} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri " $baseUrl/v1/messages" -Method Post -Headers$ headers -Body $body

如果返回正常响应，说明 API Key、Token 分组、模型权限和网络基本可用；如果返回 401 / 403 / 404 / 429，请优先查看第四节。

2.6 Windows 环境说明

本教程的 Windows 主线只介绍 PowerShell，不单独讲解 Git Bash。安装 Git for Windows 后，Claude Code 可以使用 Git Bash 提供的 Bash 工具，但 Claude Code 本身仍属于 Windows 原生安装。WSL 是独立的 Linux 环境，请进入 WSL 发行版后按照本文 Linux 章节安装和配置。

三、Linux：Bash 主线

3.1 安装 Claude Code

在普通 Linux 用户的 Bash 终端中执行：

curl -fsSL https://claude.ai/install.sh | bash

重新打开终端并验证：

claude --version

如果提示命令不存在，检查 PATH：

command -v claude

echo "$PATH"

需要更详细的安装诊断时，可执行：

claude doctor

3.2 创建用户级 settings.json

创建配置目录并打开 settings.json：

mkdir -p ~/.claude

nano ~/.claude/settings.json

写入以下内容，并替换 API Key 和模型 ID：

{

"env": {

"API_TIMEOUT_MS": "3000000",

"ANTHROPIC_BASE_URL": "https://api.aiearth.dev/",

"ANTHROPIC_AUTH_TOKEN": "<YOUR_AIOAGI_API_KEY>",

"ANTHROPIC_MODEL": "<YOUR_MODEL_ID>"

}

}

Linux 服务器和 VS Code Remote SSH 场景优先使用该用户级配置，避免依赖 .bashrc 或 .zshrc 是否被完整加载。API_TIMEOUT_MS 是可选项，不需要时可以删除。不要把含真实 API Key 的配置文件提交到项目仓库。

3.3 临时测试方式

如果只想验证当前终端，可以临时设置环境变量：

export ANTHROPIC_BASE_URL="https://api.aiearth.dev/"

export ANTHROPIC_AUTH_TOKEN="<YOUR_AIOAGI_API_KEY>"

export ANTHROPIC_MODEL="<YOUR_MODEL_ID>"

claude

长期使用仍建议写入 ~/.claude/settings.json。使用 Zsh 时也沿用同一个用户级配置文件，不需要改写为另一套配置。

3.4 验证 Linux CLI

进入测试项目并执行：

cd /path/to/your-project

which claude

claude --version

claude doctor

claude

进入 Claude Code 后执行 /status，确认 AIOAGI 地址和模型配置已生效；然后发送低风险请求，先验证读取项目能力，不要直接修改文件。

3.5 验证 VS Code Remote SSH

在本地 VS Code 安装 Remote - SSH。
连接 Linux 服务器并打开服务器上的项目。
在远程 VS Code 窗口打开命令面板，选择 Preferences: Open User Settings (JSON)。
在远程窗口的用户设置中合并以下属性：

{

"claudeCode.environmentVariables": [

{

"name": "ANTHROPIC_BASE_URL",

"value": "https://api.aiearth.dev/"

},

{

"name": "ANTHROPIC_AUTH_TOKEN",

"value": "<YOUR_AIOAGI_API_KEY>"

},

{

"name": "ANTHROPIC_MODEL",

"value": "<YOUR_MODEL_ID>"

}

]

}

重新加载远程窗口，在远程终端验证 Claude Code：

which claude

claude --version

claude

进入 Claude Code 后执行 /status。Remote SSH 的扩展进程和终端都运行在远程 Linux 环境中，因此不要只修改本地 VS Code 窗口的设置。

3.6 可选：Linux 直连 AIOAGI API 测试

只有在 CLI 或 Remote SSH 扩展报错时才需要执行。下面的请求会直接访问 https://api.aiearth.dev/v1/messages：

BASE_URL="https://api.aiearth.dev"

read -rsp "输入 AIOAGI API Key: " API_KEY

echo

read -rp "输入 AIOAGI 模型 ID: " MODEL_ID

curl -sS "$BASE_URL/v1/messages" \

-H "Authorization: Bearer $API_KEY" \

-H "anthropic-version: 2023-06-01" \

-H "Content-Type: application/json" \

--data "{\"model\":\"$MODEL_ID\",\"max_tokens\":32,\"messages\": ${\\"role\\":\\"user\\",\\"content\\":\\"Reply with OK only.\\"}$ }"

unset API_KEY MODEL_ID BASE_URL

如果返回正常响应，说明 API Key、Token 分组、模型权限和网络基本可用；如果返回 401 / 403 / 404 / 429，请优先查看第四节。测试结束后执行 unset，并避免将命令、响应或 API Key 写入历史记录和日志。

四、AIOAGI 常见问题

现象	优先检查	处理建议
claude 找不到	安装状态、PATH、终端是否重开	执行 claude --version、Get-Command claude 或 command -v claude
401 / 403	API Key、Token 分组、额度和模型权限	确认 Key 未过期，Token 分组有额度且支持所选模型
404	Base URL 是否填写正确	使用 https://api.aiearth.dev/，不要添加 /v1；实际请求路径为 /v1/messages
模型不存在	模型 ID 是否准确	到 AIOAGI 控制台核对当前 Token 分组可用的模型 ID
429	账户额度、RPM、并发限制	检查 AIOAGI 额度和限流策略，必要时联系管理员
修改后仍未生效	旧终端或 VS Code 仍在运行	完全关闭并重新打开终端和 VS Code；Remote SSH 重新加载远程窗口
CLI 已生效但 VS Code 扩展失败	claudeCode.environmentVariables 是否配置在正确窗口	Windows 配置本地用户设置；Remote SSH 配置远程窗口的用户设置
/status 地址不正确	配置文件路径或 JSON 格式	Windows 检查 %USERPROFILE%\.claude\settings.json；Linux 检查 ~/.claude/settings.json
不确定安装是否正常	CLI 和配置状态	执行 claude doctor；必要时再做 AIOAGI 直连测试

建议在项目根目录创建 CLAUDE.md，用来记录项目说明、常用命令和修改规则；不要在其中写入 API Key、私钥或生产凭据。

• 首次使用先测试读取项目结构、解释文件等低风险操作；

• 接受修改前先查看 Git Diff；

• 使用 Git 分支和小提交，保留回滚点；

• AIOAGI API Key 不要出现在 Git、截图、录屏或公开日志中；

• 如果 API Key 泄露，立即在 AIOAGI 控制台撤销并重新生成；

• 不要把真实 API Key 写入 CLAUDE.md、脚本、Issue 或公开文档。

五、项目上下文与安全建议

建议在项目根目录创建 CLAUDE.md，用来记录项目说明、常用命令和修改规则；不要在其中写入 API Key、私钥或生产凭据。

• 首次使用先测试读取项目结构、解释文件等低风险操作；

• 接受修改前先查看 Git Diff；

• 使用 Git 分支和小提交，保留回滚点；

• AIOAGI API Key 不要出现在 Git、截图、录屏或公开日志中；

• 如果 API Key 泄露，立即在 AIOAGI 控制台撤销并重新生成；

• 不要把真实 API Key 写入 CLAUDE.md、脚本、Issue 或公开文档。

六、上线前检查

□ claude --version 能正常输出；

□ claude doctor 没有关键安装错误；

□ 已经创建 AIOAGI API Key；

□ Token 分组有额度并支持选定模型；

□ ANTHROPIC_BASE_URL 为 https://api.aiearth.dev/，且没有添加 /v1；

□ 实际 Messages API 路径确认为 https://api.aiearth.dev/v1/messages；

□ ANTHROPIC_AUTH_TOKEN 已填写 AIOAGI API Key；

□ ANTHROPIC_MODEL 与控制台模型 ID 一致；

□ 使用 VS Code 扩展时，已在正确窗口配置 claudeCode.environmentVariables；

□ /status 显示正确的地址和配置来源；

□ 已完成低风险验证；必要时完成直连 API 测试；

□ API Key 没有出现在代码、截图或日志中。