使用 X-AIO Coding Helper 配置 Claude Code

本教程以 macOS、Claude Code 2.1.245 和 X-AIO Coding Helper 当前 0.9.x 主线为例，完整演示从安装、创建 API Key、粘贴密钥、选择模型到首次请求的过程。教程兼容 0.7.x 或更高版本，安装命令使用 @latest 获取当前主线的最新补丁；Linux、WSL 和 Windows 的命令会在对应步骤列出。

1. 准备环境

Claude Code 官方服务和 X-AIO 服务都受各自的地区、账号和服务条款约束。请先查看 Anthropic 支持地区，网关配置不能绕过这些政策。

Coding Helper 需要 Node.js 18 或更高版本；为了同时兼容 Claude Code 的 npm 备用安装方式，建议使用 Node.js 22 或更高版本。检查本机环境：

node --version
npm --version

如果还没有 Node.js，请从 Node.js 官网 安装 LTS 版本。使用 macOS 原生安装器时，Claude Code 本身不依赖 Node.js，但 Coding Helper 仍然需要它。

2. 按官方方式安装 Claude Code

macOS、Linux 或 WSL

在终端运行 Anthropic 当前推荐的原生安装命令：

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

安装完成后验证版本：

claude --version
claude doctor

如果终端提示 claude: command not found，先把原生安装器使用的目录加入当前 shell 的 PATH：

export PATH="$HOME/.local/bin:$PATH"

确认命令可用后，再把同一行加入 ~/.zshrc（zsh）或 ~/.bashrc（bash），然后重新打开终端。

Windows PowerShell

以普通用户身份打开 PowerShell，运行：

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

Windows CMD

在命令提示符中运行：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

备用安装方式

如果不能使用原生安装器，可以使用 Homebrew 或 npm：

# macOS Homebrew
brew install --cask claude-code

# npm 备用方式（需要 Node.js 22+）
npm install -g @anthropic-ai/claude-code

不要使用 sudo npm install -g。无论采用哪种方式，最后都应确认：

claude --version

本教程实测版本为 2.1.245。Fable 5、Sonnet 5 和 Opus 5 需要较新的 Claude Code 版本；版本过旧时先运行 claude update。

3. 创建 X-AIO API Key

1. 打开 X-AIO API 密钥管理 并登录演示账号。
2. 点击 创建新密钥。
3. 在“密钥用途”中填写一个容易识别的名称，例如 Coding Helper - Claude Code 教程。
4. 选择有效期。建议选择 90 天，不要为教程或临时测试创建永久密钥。
5. 点击 创建密钥。
6. 创建成功提示只说明“新密钥已添加到列表”，不会展示或返回一枚额外的明文密钥。点击 OK 返回密钥列表。
7. 在列表中找到 Coding Helper - Claude Code 教程，确认状态为“有效”，再点击该行的 复制 API 密钥。

新密钥并不是只在创建时显示一次。回到列表后，可以通过目标行的 显示 API 密钥 查看完整值，也可以点击 复制 API 密钥 直接写入剪贴板；本教程使用后者。列表默认只显示类似 sk-••••...•••• 的遮罩值，不要复制肉眼可见的遮罩文本。

4. 安装并启动 Coding Helper

使用 @latest 安装 Coding Helper 当前 0.9.x 主线。教程最低要求为 0.7.x 或更高版本，不锁定某个精确 patch：

npm install -g @x-all-in-one/coding-helper@latest

安装结束后，运行完整交互向导：

xaio-chelper

首次运行时，按下面的顺序完成初始设置：

1. 在语言列表中选择 [CN] 中文。
2. 向导会自动进入 API Key 页面；选择 输入 API Key，无需先返回主菜单。
3. 粘贴刚才从 API 密钥列表复制的完整值并按回车。输入会显示为圆点，不会暴露真实字符。
4. 等待 正在验证 API Key... 完成并显示 设置成功，向导随后进入主菜单。

如果本机已经运行过 Coding Helper，启动后会直接显示主菜单。此时依次选择 配置 API Key → 更新 API Key；只有尚未保存密钥时，该选项才显示为 输入 API Key。粘贴并验证成功后会自动回到主菜单。

Helper 会通过 https://llm-api.x-aio.com/v1/models 验证密钥，不会要求你登录 Anthropic 账号。它自己的配置保存在 ~/.xaio-chelper/config.yaml。

5. 配置 Claude Code 和四个模型

如果仍停留在上一节的主菜单，可以直接继续；如果已经退出，重新运行交互向导：

xaio-chelper

然后按完整菜单路径依次选择：

1. 在 主菜单 选择 配置编码工具。
2. 在工具列表选择 Claude Code。
3. 在 Claude Code 管理菜单 选择 配置模型 - (选择 Haiku/Sonnet/Opus/Fable 模型)。

模型选择界面会从 API 返回列表中逐项选择。下表是本教程使用的推荐默认配置，请选择完整模型 ID，不要只根据模型大小或排序猜测：

当前 Helper 内置的 Haiku 默认值就是带日期的 claude-haiku-4-5-20251001。如果你看到多个相近条目，仍应选择表中这个完整 ID。四个模型保存后，提示 是否立即将配置应用到 Claude Code？ (Y/n) 时直接按回车接受 Yes。

成功装载后，Claude Code 管理菜单应显示：

• 端点：https://llm-api.x-aio.com
• 四个模型与刚才的选择一致
• 状态：配置已同步

Coding Helper 0.7.x 或更高版本会把配置写入用户级的 ~/.claude/settings.json，并在 ~/.claude.json 中完成 onboarding 标记。它会保留原有的其他设置和环境变量；项目目录中的 .claude/settings.json 不会替代这一步的全局配置。

如果保存模型时没有立即应用，运行交互向导，再依次选择 主菜单 → 配置编码工具 → Claude Code → 配置装载 - (将您的配置应用到 Claude Code)。

如果你曾使用仍会写入 /anthropic 路径的早期版本，必须通过交互菜单刷新一次配置，才能清除旧路径。运行：

xaio-chelper

然后依次选择 主菜单 → 配置编码工具 → Claude Code → 配置刷新 - (更新 Claude Code 的配置)，等待提示配置装载成功。

6. 在空目录中验证真实请求

第一次运行建议使用新建的空目录，避免 Claude Code 误读或修改重要文件：

demo_dir="$(mktemp -d /tmp/xaio-claude-code-demo.XXXXXX)"
printf '%s\n' "$demo_dir"
cd "$demo_dir"
claude

如果出现目录信任提示，只确认你刚刚创建的空目录。进入 Claude Code 后执行：

/status

确认状态页中的 Anthropic base URL 为 https://llm-api.x-aio.com，认证来源为 ANTHROPIC_AUTH_TOKEN，版本足够新。本教程使用推荐默认配置时，默认模型应为 claude-opus-5；如果你在上一步选择了其他开源模型，这里会显示对应的模型 ID。

然后发送一条不修改文件的测试请求：

只回复“配置成功”，不要创建、修改或删除任何文件。

收到回复后输入 /exit 退出，再检查目录：

if [ -n "$(ls -A .)" ]; then
  ls -la .
else
  printf '%s\n' '(empty)'
fi

如果输出为 (empty)，表示本次验证没有创建文件；如果列出了文件，先停止并检查请求内容和 Claude Code 权限。也可以在 Helper 的 Claude Code 管理菜单中选择 启动 Claude Code，但新开终端直接运行 claude 更容易确认当前目录和 PATH。

确认目录仍为空后，返回 /tmp 并删除测试目录：

cd /tmp
rmdir "$demo_dir"

7. 常见问题

仍然打开 Anthropic 登录页

先退出当前 Claude Code 会话，再运行 Coding Helper：

xaio-chelper

依次选择 主菜单 → 配置编码工具 → Claude Code → 配置刷新 - (更新 Claude Code 的配置)。刷新完成后退出 Coding Helper，重新启动 Claude Code 并运行 /status；正常状态应显示 X-AIO 根端点和 ANTHROPIC_AUTH_TOKEN。不要用 Anthropic 网页登录来绕过网关配置。

报告 403 或“不可访问路径”

检查 ~/.claude/settings.json 中的 ANTHROPIC_BASE_URL 是否为：

https://llm-api.x-aio.com

如果仍是旧版的 https://llm-api.x-aio.com/anthropic，先升级到 Coding Helper 0.7.x 或更高版本：

npm install -g @x-all-in-one/coding-helper@latest

升级完成后运行：

xaio-chelper

依次选择 主菜单 → 配置编码工具 → Claude Code → 配置刷新 - (更新 Claude Code 的配置)，再完全退出并启动 Claude Code。

API Key 无效或已过期

• 确认复制的是 API 密钥列表中完整值，而不是遮罩后的 sk-xxxx...。
• 新建密钥后等待片刻，运行 xaio-chelper，再依次选择 主菜单 → 配置 API Key → 更新 API Key，重新粘贴完整密钥并等待验证成功。
• 检查密钥有效期和工作空间是否正确；必要时撤销旧密钥并创建一枚新的 90 天密钥。

模型列表中找不到某个模型

确认 API Key 属于正确的工作空间。运行 xaio-chelper，再依次选择 主菜单 → 配置编码工具 → Claude Code → 配置模型 - (选择 Haiku/Sonnet/Opus/Fable 模型)，让 Helper 重新获取最新列表。Haiku 应选择带日期的 claude-haiku-4-5-20251001；不要手动改成列表中不存在的别名。

如何确认配置是否成功

运行 xaio-chelper，再依次选择 主菜单 → 配置编码工具 → Claude Code。管理菜单应显示 X-AIO 根端点、四个已选模型和 配置已同步。然后按第 6 节进入 Claude Code，通过 /status 和一条真实请求完成最终验证。

8. 官方参考

• Claude Code 安装与更新
• Claude Code 快速开始
• 连接 LLM Gateway
• 模型配置
• Anthropic 支持地区