Claude Code

一、产品简介

Claude Code 是 Anthropic 官方推出的终端 AI 编程客户端。通过 GravitexAI（兼容 Anthropic 接口）你可以：

一键接入多家模型

通过同一接口使用 Claude 全系列、Kimi K2、GPT 等模型

多模型别名映射

固定 Opus / Sonnet / Haiku 别名与子代理模型，主副线程按需分流

无需订阅

按 token 计费，不依赖 Claude Pro 订阅

国内可用

分布式节点 + 自动故障转移，网络稳定

二、安装

安装 Node.js（已安装可跳过）

确保 Node.js 版本 ≥ 18.0。

Windows
macOS
Ubuntu / Debian

下载安装包：https://nodejs.org/dist/v22.18.0/node-v22.18.0-x64.msiWindows 上建议在 WSL 或 Git Bash 中安装并运行 Claude Code。详情参见 Claude Code Windows 安装说明。

sudo xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node
node --version

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash -
sudo apt-get install -y nodejs
node --version

卸载其他中转客户端（可选）

如果之前安装过其他中转版本的 @anthropic-ai/claude-code，建议先卸载干净：

# 检查安装位置
npm ls @anthropic-ai/claude-code
npm ls -g @anthropic-ai/claude-code

# 执行卸载
npm uninstall @anthropic-ai/claude-code
npm uninstall -g @anthropic-ai/claude-code

安装 Claude Code

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

建议保持最新版本：

npm install -g @anthropic-ai/claude-code@latest
# 或
claude update

三、获取 GravitexAI 密钥

登录控制台

访问 GravitexAI 控制台。

创建密钥

进入密钥管理 → 创建新令牌。

记录信息

base_url = "https://api.gravitex.ai"
api_key  = "sk-zbTYx*******************************fceTvn5"

Claude Code 的 ANTHROPIC_BASE_URL 不需要带 /v1 后缀，直接使用 https://api.gravitex.ai 即可（与 OpenAI 协议不同）。

四、配置接入

1. 跳过 Anthropic 官方登录（推荐）

首次启动时 Claude Code 可能尝试连接 api.anthropic.com 做登录验证。通过 GravitexAI 接入时，建议先跳过该步骤。编辑或新建 ~/.claude.json（Windows：C:\Users\<用户名>\.claude.json），写入：

{
  "hasCompletedOnboarding": true
}

2. 写入 settings.json（推荐，持久生效）

新建或编辑 ~/.claude/settings.json（Windows：C:\Users\<用户名>\.claude\settings.json）：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-zbTYx*******************************fceTvn5",
    "ANTHROPIC_BASE_URL": "https://api.gravitex.ai",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-7",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-4-5-20251001"
  }
}

将 ANTHROPIC_AUTH_TOKEN 替换为你的 GravitexAI API Key。模型 ID 请以 GravitexAI 模型广场为准。保存后新开一个终端窗口，执行：

claude "你好"

若模型正常返回，配置成功。也可在会话中执行 /status，确认 ANTHROPIC_BASE_URL 指向 https://api.gravitex.ai。

环境变量说明

变量	作用
`ANTHROPIC_BASE_URL`	请求地址，固定为 `https://api.gravitex.ai`
`ANTHROPIC_AUTH_TOKEN`	GravitexAI API Key
`ANTHROPIC_MODEL`	会话默认主模型（也可用别名如 `sonnet`、`opus`）
`ANTHROPIC_DEFAULT_OPUS_MODEL`	`/model opus`、`opusplan` 规划阶段解析到的模型
`ANTHROPIC_DEFAULT_SONNET_MODEL`	`/model sonnet`、`opusplan` 执行阶段解析到的模型
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`/model haiku` 与后台轻量任务（文件监控、补全等）
`CLAUDE_CODE_SUBAGENT_MODEL`	子代理 / Agent Teams / Workflow 使用的模型

通过第三方网关（如 GravitexAI）接入时，建议显式固定 Opus / Sonnet / Haiku 对应的完整模型 ID，避免别名解析到 Claude Code 内置默认值而与网关可用模型不一致。详见 Claude Code 模型配置。

自定义 `/model` 选择器显示与能力（可选）

通过 GravitexAI（ANTHROPIC_BASE_URL=https://api.gravitex.ai）固定模型后，/model 选择器可能直接显示原始模型 ID，且 Claude Code 不一定能识别该模型是否支持工作量级别（/effort）、扩展思考等能力。可用每个固定模型的伴随环境变量覆盖显示名称，并显式声明能力。官方说明见自定义固定模型显示和功能。

_NAME / _DESCRIPTION 在 ANTHROPIC_BASE_URL 指向 LLM 网关（如 GravitexAI）时生效；直连 api.anthropic.com 时无效。_SUPPORTED_CAPABILITIES 用于告诉 Claude Code「这个固定模型实际支持哪些能力」。

伴随环境变量（以 Opus 为例）

环境变量	说明
`ANTHROPIC_DEFAULT_OPUS_MODEL_NAME`	`/model` 选择器中的显示名称；未设置时默认为模型 ID
`ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION`	选择器中的描述；未设置时默认为 `Custom Opus model`
`ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES`	该模型支持的功能，逗号分隔列表

相同的 _NAME、_DESCRIPTION、_SUPPORTED_CAPABILITIES 后缀也适用于：

ANTHROPIC_DEFAULT_SONNET_MODEL
ANTHROPIC_DEFAULT_HAIKU_MODEL
ANTHROPIC_DEFAULT_FABLE_MODEL（若使用）
ANTHROPIC_CUSTOM_MODEL_OPTION（向选择器追加一条自定义模型时）

_SUPPORTED_CAPABILITIES 功能值 Claude Code 默认靠模型 ID 模式匹配来开启能力；网关侧的自定义 ID 往往匹配不上，导致 /effort、思考等入口被关掉。设置后，仅列表中的能力会启用，未列出的会被禁用；未设置该变量时，回退到基于模型 ID 的内置检测。

功能值	启用效果
`effort`	工作量级别与 `/effort` 命令
`xhigh_effort`	`xhigh` 工作量级别
`max_effort`	`max` 工作量级别
`thinking`	扩展思考
`adaptive_thinking`	按任务复杂度动态分配思考的自适应推理
`interleaved_thinking`	工具调用之间的思考

完整示例（GravitexAI）

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-zbTYx*******************************fceTvn5",
    "ANTHROPIC_BASE_URL": "https://api.gravitex.ai",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",

    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "Opus via GravitexAI",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION": "Claude Opus 经 GravitexAI 路由",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES": "effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking",

    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "Sonnet via GravitexAI",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION": "Claude Sonnet 经 GravitexAI 路由",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES": "effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking",

    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "Haiku via GravitexAI",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION": "Claude Haiku 经 GravitexAI 路由，适合后台轻量任务"
  }
}

也可在 shell 中临时导出（效果相同）：

export ANTHROPIC_BASE_URL="https://api.gravitex.ai"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxx"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-7"
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME="Opus via GravitexAI"
export ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION="Claude Opus 经 GravitexAI 路由"
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES="effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking"

向选择器追加一条自定义模型（可选） 若还需要在 /model 底部增加一个网关专属条目（不替换内置 opus / sonnet / haiku 别名），可使用：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gravitex.ai",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxx",
    "ANTHROPIC_CUSTOM_MODEL_OPTION": "kimi-k2-250905",
    "ANTHROPIC_CUSTOM_MODEL_OPTION_NAME": "Kimi K2 via GravitexAI",
    "ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION": "性价比优先的编码模型"
  }
}

ANTHROPIC_CUSTOM_MODEL_OPTION 中的模型 ID 不会做官方校验，可填 GravitexAI 接受的任意模型字符串。省略 _NAME / _DESCRIPTION 时，名称默认为模型 ID，描述默认为 Custom model (<model-id>)。配置保存后新开终端，运行 claude，执行 /model 即可看到自定义名称与描述；在已声明 effort 等能力的模型上可使用 /effort。

3. 临时环境变量（可选）

不写 settings.json 时，也可在当前终端临时导出：

Mac / Linux
Windows CMD
Windows PowerShell

export ANTHROPIC_BASE_URL="https://api.gravitex.ai"
export ANTHROPIC_AUTH_TOKEN="sk-zbTYx*******************************fceTvn5"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-7"
cd your-project-folder
claude

set ANTHROPIC_BASE_URL=https://api.gravitex.ai
set ANTHROPIC_AUTH_TOKEN=sk-zbTYx*******************************fceTvn5
set ANTHROPIC_MODEL=claude-sonnet-4-6
set ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
set ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
set ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7
cd your-project-folder
claude

$env:ANTHROPIC_BASE_URL="https://api.gravitex.ai"
$env:ANTHROPIC_AUTH_TOKEN="sk-zbTYx*******************************fceTvn5"
$env:ANTHROPIC_MODEL="claude-sonnet-4-6"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-7"
cd your-project-folder
claude

4. 扩展上下文窗口（可选）

Claude Code 默认按约 200K 上下文管理会话。处理大型仓库或长对话时，若所用模型支持 1M 上下文，可任选其一： 方式一：环境变量

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxx",
    "ANTHROPIC_BASE_URL": "https://api.gravitex.ai",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1000000"
  }
}

方式二：模型名加 [1m] 后缀

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxx",
    "ANTHROPIC_BASE_URL": "https://api.gravitex.ai",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-7[1m]"
  }
}

修改后需新开终端再启动 Claude Code。更多说明见扩展上下文。

五、模型别名与切换

Claude Code 支持模型别名，无需每次记完整版本号（网关场景下请先用上一节的环境变量固定映射）：

别名	行为
`sonnet`	日常编码，解析到 `ANTHROPIC_DEFAULT_SONNET_MODEL`
`opus`	复杂推理，解析到 `ANTHROPIC_DEFAULT_OPUS_MODEL`
`haiku`	轻量任务，解析到 `ANTHROPIC_DEFAULT_HAIKU_MODEL`
`opusplan`	Plan Mode 用 Opus，执行阶段自动切到 Sonnet
`sonnet[1m]` / `opus[1m]`	启用 1M 上下文窗口（需模型支持）

切换方式（优先级从高到低大致为：会话内 /model → 启动参数 → 环境变量 → settings）：

# 启动时指定
claude --model opus

# 会话内切换
/model              # 打开选择器
/model sonnet
/model opusplan
/model claude-opus-4-7

也可在 ~/.claude/settings.json 顶层设置持久默认模型：

{
  "model": "opus",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gravitex.ai",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxx"
  }
}

六、推荐模型组合

场景	主模型 (`ANTHROPIC_MODEL`)	Haiku / 副线程	Opus 别名映射
生产级开发（首选）	`claude-opus-4-7`	`claude-haiku-4-5-20251001`	`claude-opus-4-7`
日常开发（推荐）	`claude-sonnet-4-6`	`claude-haiku-4-5-20251001`	`claude-opus-4-7`
性价比优先	`kimi-k2-250905`	`claude-haiku-4-5-20251001`	`claude-opus-4-7`
长上下文	`claude-sonnet-4-5-20250929`	`claude-haiku-4-5-20251001`	`claude-opus-4-7`
快速验证	`claude-haiku-4-5-20251001`	`claude-haiku-4-5-20251001`	—

完整模型 ID 请参考 GravitexAI 模型广场。

七、IDE 插件

完成上述 CLI / settings.json 配置后，IDE 插件可复用同一套环境变量。

VS Code：扩展市场搜索 Claude Code for VS Code 安装，详见 Claude 插件（VS Code）
JetBrains：扩展市场搜索 Claude Code 并安装，重启后使用

八、常见问题

Unable to connect to Anthropic services / Failed to connect to api.anthropic.com

Claude Code 正在尝试连接官方服务而非 GravitexAI。排查：

执行 /status，确认 ANTHROPIC_BASE_URL 为 https://api.gravitex.ai；
确认 ~/.claude.json 中 hasCompletedOnboarding 为 true；
修改配置后新开终端再运行 claude；
升级到最新版：npm install -g @anthropic-ai/claude-code@latest。

401 / API Key 无效

检查 ANTHROPIC_AUTH_TOKEN 是否完整、是否有多余空格或换行。
在 GravitexAI 控制台确认 Key 未被禁用。
确保账户余额充足。

404 / endpoint 错误

Claude Code 的 ANTHROPIC_BASE_URL 不要加 /v1，使用 https://api.gravitex.ai 即可（与 OpenAI 协议不同）。

400 / ValidationException / Extra inputs are not permitted

该问题通常由 Claude Code 的实验性 Beta 功能参数（如 cache_control、scope 等）引起，这些参数在 AWS Bedrock Claude 通道中不被支持。解决方法：在 settings.json 中添加环境变量关闭实验性 Beta 功能：

"env": {
  "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
}

详细步骤、排查清单和原理说明请参考完整文档 → Claude Code 报错 400 解决指南

如何在 Claude Code 中切换模型？

/model              # 打开选择器 / 查看当前模型
/model haiku        # 切换到 ANTHROPIC_DEFAULT_HAIKU_MODEL
/model sonnet       # 切换到 ANTHROPIC_DEFAULT_SONNET_MODEL
/model opus         # 切换到 ANTHROPIC_DEFAULT_OPUS_MODEL
/model opusplan     # Plan 用 Opus，执行用 Sonnet

或使用 claude --model <alias|name> 启动，或修改 settings.json 后重启。

模型 ID 报错 not found / is not a recognized model id

请使用 GravitexAI 模型列表中的完整 ID，例如：

✅ claude-sonnet-4-5-20250929
❌ claude-sonnet-4-5（部分场景日期后缀不可省略）

自定义 ANTHROPIC_BASE_URL 时，Claude Code 通常会透传任意模型字符串；若仍报错，请核对模型是否已在控制台开通。

别名切换后模型不对

网关场景下请在 settings.json 中同时设置 ANTHROPIC_DEFAULT_OPUS_MODEL / SONNET / HAIKU，再使用 /model opus 等别名。仅设置 ANTHROPIC_MODEL 不会改变别名解析目标。

如何减少 token 消耗？

副线程 / 子代理使用 Haiku（ANTHROPIC_DEFAULT_HAIKU_MODEL、CLAUDE_CODE_SUBAGENT_MODEL）；
日常开发用 Sonnet，复杂任务再用 Opus 或 opusplan；
用 /effort 降低工作量级别（支持的模型上）；
使用 /clear 清理冗余上下文。

如何统一团队配置？

将 ANTHROPIC_BASE_URL 与模型映射写入项目或托管 settings.json，成员各自填入自己的 ANTHROPIC_AUTH_TOKEN。也可用 CC Switch 等工具在多 Key 间切换，详见 CC Switch。

九、参考链接

Claude Code 官方文档：https://code.claude.com/docs/zh-CN
模型配置（别名 / 环境变量 / 自定义显示）：https://code.claude.com/docs/zh-CN/model-config
GravitexAI 控制台：https://maas.gravitex.ai
API 地址：https://api.gravitex.ai
模型广场：https://maas.gravitex.ai/#/models
密钥管理：https://maas.gravitex.ai/#/api-keys
400 报错解决指南：Claude Code 报错 400 解决指南

对话型 AI

编程开发

AI Agent

技术工程

翻译场景

一、产品简介

一键接入多家模型

多模型别名映射

无需订阅

国内可用

二、安装

安装 Node.js（已安装可跳过）

卸载其他中转客户端（可选）

安装 Claude Code

三、获取 GravitexAI 密钥

四、配置接入

1. 跳过 Anthropic 官方登录（推荐）

2. 写入 settings.json（推荐，持久生效）

环境变量说明

自定义 `/model` 选择器显示与能力（可选）

3. 临时环境变量（可选）

4. 扩展上下文窗口（可选）

五、模型别名与切换

六、推荐模型组合

七、IDE 插件

八、常见问题

九、参考链接

​一、产品简介

一键接入多家模型

多模型别名映射

无需订阅

国内可用

​二、安装

​安装 Node.js（已安装可跳过）

​卸载其他中转客户端（可选）

​安装 Claude Code

​三、获取 GravitexAI 密钥

​四、配置接入

​1. 跳过 Anthropic 官方登录（推荐）

​2. 写入 settings.json（推荐，持久生效）

​环境变量说明

​自定义 /model 选择器显示与能力（可选）

​3. 临时环境变量（可选）

​4. 扩展上下文窗口（可选）

​五、模型别名与切换

​六、推荐模型组合

​七、IDE 插件

​八、常见问题

​九、参考链接

一、产品简介

二、安装

安装 Node.js（已安装可跳过）

卸载其他中转客户端（可选）

安装 Claude Code

三、获取 GravitexAI 密钥

四、配置接入

1. 跳过 Anthropic 官方登录（推荐）

2. 写入 settings.json（推荐，持久生效）

环境变量说明

自定义 `/model` 选择器显示与能力（可选）

3. 临时环境变量（可选）

4. 扩展上下文窗口（可选）

五、模型别名与切换

六、推荐模型组合

七、IDE 插件

八、常见问题

九、参考链接