Claude Code 接入#

Claude Code 是一个智能编码工具,可以在终端中运行,通过自然语言命令交互帮助开发者快速完成代码生成、调试、重构等任务。

通过修改本地的持久化配置文件,你可以轻松将 Claude Code 的默认请求地址指向 UniGateway 提供的原生 API 接口,实现稳定高效的编码工作流。由于 UniGateway 提供的是原生 Claude 接口,无需进行任何模型名称替换或映射。

提示: 如果您在使用过程中遇到 tool_search 调用导致的 400 错误,可以在下方的配置文件中追加 "ENABLE_TOOL_SEARCH": "0" 来暂时解决。

步骤一:安装 Claude Code#

前提条件:

• 您需要安装 Node.js 18 或更新版本环境
• MacOS/Linux 用户推荐使用 nvm 或 fnm 方式安装 Node.js,不推荐直接安装包(避免后续遇到系统权限问题)
• Windows 用户推荐预先安装 Git for Windows

打开终端(Terminal 或 PowerShell),运行以下命令全局安装 Claude Code:

npm install -g @anthropic-ai/claude-code

安装完成后,运行如下命令查看版本,若显示版本号则表示安装成功:

claude --version

步骤二:配置永久化环境变量 (UniGateway)#

为了让 Claude Code 永久连接到 UniGateway 而不需要每次启动都手动设置环境变量,我们需要直接修改 Claude Code 的全局本地配置文件。

请根据您的操作系统,在对应的用户目录下新建或编辑这两个 JSON 配置文件。

1. 配置 settings.json(接口与密钥配置)#

这个文件用于永久存储 API 环境变量。

• MacOS & Linux 路径: ~/.claude/settings.json
• Windows 路径: C:\Users\你的用户名\.claude\settings.json

如果该目录或文件不存在,请手动创建。将以下内容填入 settings.json,并替换为你自己的 API Key:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-在此处填写你的Unigateway_API_Key",
    "ANTHROPIC_BASE_URL": "https://api.unigateway.ai"
  }
}

2. 配置 .claude.json(跳过官方强制引导)#

这个文件用于标记已完成初始化,防止每次启动都弹出要求登录 Anthropic 官方账号的授权页面。

• MacOS & Linux 路径: ~/.claude.json
• Windows 路径: C:\Users\你的用户名\.claude.json

新建或编辑该文件,填入以下内容:

{
  "hasCompletedOnboarding": true
}

注意:

• 确保 JSON 文件格式完全正确(例如不要遗漏引号,不要有多余的逗号)。
• 配置文件修改完成后,请务必关闭当前终端窗口,并重新打开一个新的终端窗口,以确保配置被正确加载。

步骤三:开始使用 Claude Code#

配置完成后,使用终端进入你的任意代码项目工作目录,直接执行以下命令即可启动:

claude

启动时:

1. 若系统提示询问「Do you want to use this API key?」,选择 Yes 即可。
2. 随后选择信任 Claude Code 访问该文件夹里的文件。

进入交互界面后,你可以输入 /status 命令来确认当前连接的模型状态。由于配置了原生接口,你可以直接使用 claude-opus-4-6 等官方原生模型进行高效开发。

常见问题排查#

手工修改配置后不生效?

• 确认是否已经关闭并重新打开了命令行窗口。
• 检查 settings.json 和 .claude.json 文件路径是否正确(注意 .claude 文件夹与 .claude.json 文件的层级区别)。
• 确认 JSON 格式是否合法,可使用在线 JSON 校验工具检查是否缺少括号或逗号。
• 若依然无效,可尝试删除 settings.json 文件后重新创建并严格按照上述格式填入。