> ## 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.

# macOS

> 在 macOS 上安装 Claude Code，并通过 AIOAGI 接入 Claude 系列模型。

Claude Code 可以直接运行在 macOS 终端中。你可以安装 Claude Code CLI，把它指向 AIOAGI 的 Anthropic 兼容端点，再使用 AIOAGI API Key 调用平台支持的 Claude 系列模型。

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

## 准备条件

* macOS 12 或更高版本
* 可用的终端环境，默认 `zsh` 即可
* Git
* 可用的 AIOAGI API Key
* 一个本地代码项目，用于验证 Claude Code 是否可正常读取仓库
* 如果使用 `npm` 安装方式，需要 Node.js `18+` 或当前 LTS 版本

<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="安装命令行工具">
    如果你的系统还没有 Git 或编译工具，先安装 Xcode Command Line Tools：

    ```bash theme={null}
    xcode-select --install
    ```

    安装后验证 Git：

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

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

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

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

    ```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。建议为 Claude Code 单独创建 Token 组，便于统计用量和控制额度。
  </Step>

  <Step title="写入 Claude Code 配置">
    推荐把 AIOAGI 接入参数写入当前 macOS 用户的 `~/.claude/settings.json`。该配置对当前用户的 Claude Code 会话生效，也更适合 VS Code 等 IDE 场景。
  </Step>

  <Step title="启动 Claude Code">
    进入你的代码项目目录，执行 `claude`。首次接入时先发送一个简单问题，确认模型能正常返回内容。
  </Step>
</Steps>

## AIOAGI 接入配置

### 推荐方式：使用 `settings.json`

创建配置目录和配置文件：

```bash theme={null}
mkdir -p ~/.claude
nano ~/.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]"
}
```

如果你的网络更适合 CDN 加速线路，也可以把 `ANTHROPIC_BASE_URL` 改成：

```json theme={null}
"ANTHROPIC_BASE_URL": "https://api.aiearth.vip/"
```

保存后重新打开终端和 VS Code，再执行 `claude` 验证。

<Warning>
  `ANTHROPIC_MODEL` 和 `model` 仅作为配置示例。请在控制台或开发者指南中确认当前 API Key 可访问的 Claude 模型 ID 或平台别名后再配置。
</Warning>

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

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

```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
```

如果要长期使用，macOS 默认 `zsh` 可以写入 `~/.zshrc`：

```bash theme={null}
cat <<'EOF' >> ~/.zshrc
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 ~/.zshrc
```

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

<Note>
  `settings.json` 更适合作为主配置。shell 环境变量适合临时测试、排障，或只想让某个终端窗口使用独立配置的场景。
</Note>

### 项目级配置

如果只想让某个项目使用独立的 AIOAGI 配置，可以在项目目录写入 `.claude/settings.local.json`：

```bash theme={null}
mkdir -p .claude
nano .claude/settings.local.json
```

示例：

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

不要把包含真实 API Key 的 `~/.claude/settings.json`、`.claude/settings.local.json`、shell 配置文件或终端截图提交到公开仓库。

## 启动和验证

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

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

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

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

如果 Claude Code 能正常读取仓库并返回结果，说明 CLI 安装、配置文件和 API Key 已基本可用。

## 集成到 VS Code

安装好 Claude Code CLI 后，你可以在 VS Code 中安装 Claude Code 扩展。

<Steps>
  <Step title="打开扩展面板">
    在 VS Code 中点击 **Extensions**，搜索 `Claude Code`。
  </Step>

  <Step title="安装扩展">
    安装 Claude Code 官方扩展，然后重载 VS Code。
  </Step>

  <Step title="打开项目">
    在 VS Code 中打开你的项目目录，并确认当前集成终端可以执行 `claude --version`。
  </Step>

  <Step title="验证集成">
    先在 VS Code 集成终端里执行 `claude`，再使用扩展入口检查是否能正常调用 Claude Code。
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/claude-code/vscode-extension.png?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=de59a9fa312ff565013e2a2f357c890f" alt="VS Code 中安装 Claude Code 扩展示例" width="1080" height="644" data-path="images/claude-code/vscode-extension.png" />
</Frame>

## 常见问题

<AccordionGroup>
  <Accordion title="执行 `claude` 提示命令不存在" icon="terminal">
    关闭并重新打开终端。然后执行 `echo $PATH` 和 `which claude`，确认安装目录已经加入 `PATH`。如果你使用 `npm` 安装，请执行 `npm prefix -g` 核对全局安装目录。
  </Accordion>

  <Accordion title="`npm install -g` 权限不足" icon="lock">
    不建议长期使用 `sudo npm install -g`。优先使用官方安装脚本，或使用 `nvm` 管理 Node.js，再安装 `@anthropic-ai/claude-code`。
  </Accordion>

  <Accordion title="认证失败或返回 401 / 403" icon="key">
    检查 `~/.claude/settings.json` 是否是合法 JSON，并确认 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL` 和 `model` 是否填写正确。再检查 Token 组额度、模型权限和网络线路。
  </Accordion>

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

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

  <Accordion title="VS Code 扩展无法读取配置" icon="plug">
    修改 `settings.json` 或 shell 配置后，重新打开 VS Code。优先确认 VS Code 集成终端中执行 `claude` 是否正常。
  </Accordion>
</AccordionGroup>

## 使用建议

* 为 Claude Code 单独创建 API Key，便于统计开发工具用量
* 先用小额度 Token 组完成连通性测试，再切换到正式额度
* 优先使用 `~/.claude/settings.json` 固化 AIOAGI 接入参数
* 临时排障时再使用 `export ANTHROPIC_BASE_URL` 和 `export ANTHROPIC_AUTH_TOKEN`
* 模型名、价格和支持策略可能变化，请以控制台和开发者指南为准

## 相关文档

* [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)