> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioagi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Linux

> 在 Linux 服务器上安装 Claude Code，并通过 AIOAGI 接入 Claude 系列模型后使用 VS Code SSH 远程开发。

Claude Code 可以直接运行在 Linux 服务器上。你可以在服务器端安装 CLI，配置 AIOAGI API Key 和 Claude 模型，再通过本地 VS Code Remote SSH 连接服务器使用 Claude Code 辅助开发。

<Info>
  界面、模型名、端点和支持策略可能变化，请以控制台、开发者指南和 Anthropic 官方文档的最新说明为准。
</Info>

<Card title="参考原文" icon="newspaper" href="https://blog.csdn.net/qq_36396104/category_13108723.html">
  查看 Claude Code 配置与使用相关的原文说明。
</Card>

## 准备条件

* Linux 服务器或云主机
* 一个普通 Linux 用户账号，不建议使用 `root` 用户安装和运行 Claude Code
* Node.js `18+` 或当前 LTS 版本
* Git
* 可用的 AIOAGI API Key
* 本地 VS Code，并安装 Remote SSH 相关能力
* 一个服务器端代码项目，用于验证 Claude Code 是否可正常工作

<CardGroup cols={2}>
  <Card title="Anthropic 安装文档" href="https://code.claude.com/docs/en/quickstart">
    查看 Claude Code 的系统要求、安装命令和验证方式。
  </Card>

  <Card title="Anthropic Gateway 文档" href="https://code.claude.com/docs/en/llm-gateway">
    查看 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN` 和模型环境变量的配置方式。
  </Card>

  <Card title="AIOAGI API Key 指南" href="/api-key-guide">
    如果你还没有创建 API Key，可以先完成控制台配置。
  </Card>

  <Card title="开发者指南" href="https://aiearthdev.apifox.cn/">
    核对当前端点、模型和接口说明。
  </Card>
</CardGroup>

## 安装步骤

<Steps>
  <Step title="准备 Linux 用户环境">
    使用普通用户登录服务器。后续命令默认在该用户的 `bash` 终端中执行。

    ```bash theme={null}
    whoami
    pwd
    ```

    如果你使用的是 `zsh`，下文写入 `~/.bashrc` 的配置可改写到 `~/.zshrc`。
  </Step>

  <Step title="安装 Node.js">
    你可以使用系统包管理器安装 Node.js，也可以使用 Node.js 官网下载的 Linux `tar.xz` 压缩包安装到用户目录。

    如果使用压缩包方式，可先把下载好的文件上传到服务器用户目录，然后执行：

    ```bash theme={null}
    cd ~
    mkdir -p ~/local/node
    tar -xJf ~/node-v*-linux-*.tar.xz -C ~/local/node --strip-components=1
    echo 'export PATH="$HOME/local/node/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc
    ```

    验证安装结果：

    ```bash theme={null}
    node --version
    npm --version
    ```
  </Step>

  <Step title="安装 Git">
    在 Ubuntu 或 Debian 系统中，可使用：

    ```bash theme={null}
    sudo apt update
    sudo apt install -y git
    ```

    在 RHEL、CentOS、Rocky Linux 或 AlmaLinux 中，可使用：

    ```bash theme={null}
    sudo dnf install -y git
    ```

    安装后验证：

    ```bash theme={null}
    git --version
    ```
  </Step>

  <Step title="安装 Claude Code">
    官方安装脚本适用于 Linux、macOS 和 WSL：

    ```bash theme={null}
    curl -fsSL https://claude.ai/install.sh | bash
    ```

    如果你的团队已经统一使用 Node.js，也可以用 `npm` 安装 Claude Code CLI：

    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code
    ```

    安装后执行下面两个命令确认安装结果：

    ```bash theme={null}
    claude --version
    claude doctor
    ```
  </Step>

  <Step title="创建 AIOAGI API Key">
    登录 AIOAGI 控制台，在 **令牌管理** 中创建可用于 Claude 模型的 API Key。确认令牌分组和额度设置满足当前模型调用需求。
  </Step>

  <Step title="写入 settings.json">
    把 AIOAGI 接入参数写入当前 Linux 用户的 `~/.claude/settings.json`。该配置会应用到当前用户的所有 Claude Code 会话。
  </Step>
</Steps>

## 安装界面示例

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/claude-code/nodejs-download.png?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=f5497bc6f37415623a97138ed45df70c" alt="Node.js 下载页面示例" width="1080" height="600" data-path="images/claude-code/nodejs-download.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/claude-code/linux-terminal-check.svg?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=1337ac05048f6edfba44f5abfda1c18e" alt="Linux 终端中验证 Node.js、Git 和 Claude Code 的示意图" width="1200" height="640" data-path="images/claude-code/linux-terminal-check.svg" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/claude-code/token-management.png?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=cbd223c267540b78626ca39ec116fd3a" alt="AIOAGI 控制台令牌管理界面示例" width="1080" height="305" data-path="images/claude-code/token-management.png" />
</Frame>

## Claude Code settings.json 配置

Claude Code 可以从 `settings.json` 读取环境变量和默认模型。Linux 服务器建议使用当前用户的 `~/.claude/settings.json`，避免把 API Key 写入项目仓库。

```bash theme={null}
mkdir -p ~/.claude
vim ~/.claude/settings.json
```

写入下面的内容，并把 `ANTHROPIC_AUTH_TOKEN` 改成你的 AIOAGI API Key：

```json theme={null}
{
  "env": {
    "API_TIMEOUT_MS": "3000000",
    "ANTHROPIC_BASE_URL": "https://api.aiearth.dev/",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-aioagi-api-key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  },
  "model": "sonnet[1m]"
}
```

保存后重新打开终端，或重新连接 VS Code Remote SSH 窗口，再执行 `claude` 验证。

如果你的网络更适合 CDN 加速线路，也可以把 `ANTHROPIC_BASE_URL` 改成 `https://api.aiearth.vip/`。端点、模型名和支持策略可能变化，请以控制台和开发者指南显示的信息为准。

如需只让某个项目使用独立配置，可在项目目录写入 `.claude/settings.local.json`。不要把包含真实 API Key 的 `.claude/settings.json`、`.claude/settings.local.json` 或截图提交到公开仓库。

<Warning>
  `ANTHROPIC_MODEL` 和 `model` 应填写控制台当前可用的 Claude 系列模型 ID 或别名。模型名会随平台策略变化，请先在控制台或开发者指南中确认后再配置。
</Warning>

### 快速验证：使用 shell 环境变量

如果你只想在当前 SSH 会话中快速验证，可以临时导出环境变量：

```bash theme={null}
export ANTHROPIC_BASE_URL="https://api.aiearth.dev/"
export ANTHROPIC_AUTH_TOKEN="sk-your-aioagi-api-key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
claude
```

如果要长期使用 `bash`，可以写入 `~/.bashrc`：

```bash theme={null}
cat <<'EOF' >> ~/.bashrc
export ANTHROPIC_BASE_URL="https://api.aiearth.dev/"
export ANTHROPIC_AUTH_TOKEN="sk-your-aioagi-api-key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
EOF
source ~/.bashrc
```

如果你使用 `zsh`，把上面的 `~/.bashrc` 改成 `~/.zshrc`。

<Note>
  服务器和 VS Code Remote SSH 场景优先使用 `~/.claude/settings.json`。shell 环境变量适合临时测试、排障，或只想让某个终端会话使用独立配置的场景。
</Note>

### 检查实际生效的配置

修改配置后，可以先检查命令路径和关键环境变量：

```bash theme={null}
which claude
claude --version
env | grep '^ANTHROPIC_'
```

如果你主要依赖 `settings.json`，`env | grep` 不一定能看到这些变量。此时以 `~/.claude/settings.json` 中的 `env` 配置为准。

## 启动和验证

进入你的代码项目后，执行：

```bash theme={null}
claude
```

你可以先用下面这类简单提示词验证接入是否成功：

```text theme={null}
请先阅读当前仓库结构，再总结主要目录和入口文件。
```

如果 Claude Code 能正常读取仓库并返回结果，说明 CLI 安装、环境变量和 API Key 已基本可用。

## 集成到 VS Code SSH

本地 VS Code 可以通过 Remote SSH 连接 Linux 服务器，并在远程环境中使用 Claude Code。

<Steps>
  <Step title="安装 Remote SSH">
    在本地 VS Code 中点击 **Extensions**，搜索并安装 `Remote - SSH`。
  </Step>

  <Step title="配置 SSH 主机">
    在本机 `~/.ssh/config` 中添加服务器配置。示例：

    ```sshconfig theme={null}
    Host aioagi-linux
      HostName your-server-ip
      User your-linux-user
      IdentityFile ~/.ssh/id_rsa
    ```
  </Step>

  <Step title="连接服务器">
    在 VS Code 中执行 **Remote-SSH: Connect to Host**，选择刚刚配置的主机，并打开服务器上的项目目录。
  </Step>

  <Step title="安装 Claude Code 扩展">
    连接到远程服务器后，在远程扩展环境中搜索 `Claude Code`，安装 Claude Code 官方扩展。
  </Step>

  <Step title="验证远程终端">
    打开 VS Code 远程终端，执行 `node --version`、`npm --version`、`git --version` 和 `claude --version`，确认命令读取的是服务器端环境。
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/claude-code/vscode-ssh-claude.svg?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=3241fffa03336d74753167e8afd13e50" alt="VS Code Remote SSH 连接 Linux 服务器并使用 Claude Code 的示意图" width="1200" height="640" data-path="images/claude-code/vscode-ssh-claude.svg" />
</Frame>

## VS Code 远程配置

有些 VS Code Remote SSH 会话不会完整加载交互式 shell 的 `~/.bashrc`。优先把 AIOAGI 接入参数写入服务器当前用户的 `~/.claude/settings.json`，这样 CLI 和远程扩展可以读取同一份配置。

```bash theme={null}
mkdir -p ~/.claude
vim ~/.claude/settings.json
```

配置内容如下：

```json theme={null}
{
  "env": {
    "API_TIMEOUT_MS": "3000000",
    "ANTHROPIC_BASE_URL": "https://api.aiearth.dev/",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-aioagi-api-key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  },
  "model": "sonnet[1m]"
}
```

保存后重新打开 VS Code Remote SSH 窗口，再在远程终端中执行 `claude` 验证。

<Warning>
  不要把包含真实 API Key 的 `settings.json`、`.bashrc` 或截图提交到公开仓库。多人共用服务器时，建议每个 Linux 用户使用独立 API Key。
</Warning>

## 常见问题

<AccordionGroup>
  <Accordion title="执行 `claude` 提示命令不存在" icon="terminal">
    先执行 `which claude` 和 `echo $PATH`，确认 Claude Code 安装目录已经加入 `PATH`。如果你使用 `npm` 安装，再执行 `node --version`、`npm --version` 和 `npm prefix -g`，确认 Node.js 与全局安装路径是否生效。
  </Accordion>

  <Accordion title="`npm install -g` 权限不足" icon="lock">
    不建议直接切换到 `root` 运行 Claude Code。优先使用官方安装脚本，或把 Node.js 安装到当前用户目录，再配置用户级 npm 全局目录并重新安装 `@anthropic-ai/claude-code`。
  </Accordion>

  <Accordion title="Claude Code 启动后认证失败或返回 403" icon="key">
    检查 `~/.claude/settings.json` 是否是合法 JSON，并确认 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL` 和 `model` 是否填写正确。再检查 Token 组是否支持当前模型，并确认是否需要切换网络线路。你也可以继续参考 [常见问题](/faq) 中的 Claude Code 排障条目。
  </Accordion>

  <Accordion title="配置后仍未生效" icon="gear">
    如果配置后仍未生效，或仍返回 Anthropic 官方接口的认证、验证错误，请先重新打开本地终端、远程 shell 和 VS Code Remote SSH 窗口。再执行 `claude` 重新测试。如果仍不生效，请重启对应服务器或主机后再测试。问题仍存在时，可以通过微信或 QQ 联系平台管理员协助排查。
  </Accordion>

  <Accordion title="VS Code 扩展无法读取 API Key" icon="plug">
    先确认远程服务器当前用户存在 `~/.claude/settings.json`，并检查文件中的 API Key 和模型配置。修改后重新加载 VS Code Remote SSH 窗口。
  </Accordion>

  <Accordion title="模型名不生效或不可用" icon="sparkles">
    先到控制台确认当前 API Key 可访问的 Claude 模型列表，再核对模型 ID 是否完全一致。如果平台近期调整了模型别名或支持策略，请以控制台和开发者指南最新信息为准。
  </Accordion>
</AccordionGroup>

## 使用建议

* 为服务器端 Claude Code 单独创建 API Key，便于统计用量和控制额度
* 先用小额度 Token 组完成安装和连通性测试，再切换到正式额度
* 多人共用服务器时，建议按 Linux 用户隔离 API Key 和 `~/.claude` 配置
* 使用 VS Code Remote SSH 时，确认扩展安装在远程服务器环境，而不是只安装在本地
* 长期使用时，建议固定 Node.js 安装方式和模型 ID，并定期到控制台核对模型可用性

## 相关文档

* [Anthropic: Claude Code quickstart](https://code.claude.com/docs/en/quickstart)
* [Anthropic: Environment variables](https://code.claude.com/docs/en/env-vars)
* [Anthropic: LLM gateway configuration](https://code.claude.com/docs/en/llm-gateway)
* [Anthropic: Claude Code settings](https://code.claude.com/docs/en/settings)
* [VS Code: Remote SSH](https://code.visualstudio.com/docs/remote/ssh)