Agent Gateway operational · 14ms
quickstart · 5 分钟

接入 Agent Gateway
三种客户端，一把 API Key

Claude Code CLI 与 VS Code 扩展共用 ~/.claude/settings.json 两行 env；Claude Desktop 走开发者模式 GUI 配置。本页是保姆级图文，按步骤照做即可。

看配置步骤 ↓ 看避坑指南
向管理员领取 API Key · 每人一把
FILE ~/.claude/settings.json 
1{
2  "env": {
3    "ANTHROPIC_BASE_URL": "https://<gateway-domain>",
4    "ANTHROPIC_API_KEY": "cap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
5  },
6  "hasCompletedOnboarding": true
7}
CLIENTS
3
CLI · VS Code · Desktop
FILES
1
edit · settings.json
CODE
0
lines changed
DOWNTIME
0
switch any time
step 01 · 安装客户端

装一个就行
三种客户端任选

CLI 与 VS Code 扩展共用一份 ~/.claude/settings.json；桌面端独立，走开发者模式 GUI。下面每个安装命令都给了 copy 按钮，直接粘贴执行。

01
Claude Code (CLI)
settings.json

直接读取 ~/.claude/settings.json 的 env。配置完 claude 命令即接入网关。

安装命令
npm i -g @anthropic-ai/claude-code
02
VS Code · Cursor · Trae · JetBrains 等
市场安装 · 复用 env

任何 IDE 上的 Claude Code 扩展都读同一份 settings.json 的 env — 配置一次到处通用，命令面板执行 Claude Code: Start 即接入。

安装命令
code --install-extension anthropic.claude-code
03
Claude Desktop
Developer Mode

桌面端不读 settings.json。下载后先 Cmd+Q 完全退出，再走 Developer Mode GUI 配置。

安装命令
https://claude.ai/download
TIP 如果你只用 VS Code，那就装 扩展 一个就够了 — 它会在首次启动时自动把 CLI 拉下来。命令行重度用户两个都装。Claude Desktop 与前两者互不影响。
step 02 · 配置 settings.json

粘贴这段到 settings.json
CLI · VS Code · 其它 IDE 共用

打开 ~/.claude/settings.json，把右边整段 JSON 粘进去，<gateway-domain> 与 cap_xxxx…xxxx 换成管理员给你的值。 注意 hasCompletedOnboarding 与 env 平级，不要写到 env 里面 — 这条避免首次跑 claude 卡在登录页（见下方避坑）。

IDE 任何接入 Claude Code 插件的 IDE 配置方法完全相同 — Cursor、 Trae、 Windsurf、 JetBrains 系（IntelliJ / WebStorm / PyCharm / GoLand 等）。 它们的 Claude Code 插件都读这同一份 ~/.claude/settings.json，配置一次到处通用，无需在 IDE 里再单独设置。
📁 找不到这个文件？点开看具体路径与打开方式
macOS
/Users/你的用户名/.claude/settings.json
终端（推荐）：code ~/.claude/settings.json
或 Finder → 菜单「前往 → 个人」→ 按 ⌘+⇧+. 显示隐藏文件 → 进 .claude 文件夹
Windows
C:\Users\你的用户名\.claude\settings.json
PowerShell（推荐）：code $env:USERPROFILE\.claude\settings.json
或资源管理器地址栏输入 %USERPROFILE% 回车 → 「查看 → 隐藏的项目」勾上 → 进 .claude 文件夹（开头的点 = 隐藏文件夹，不勾这项看不到）
Linux
/home/你的用户名/.claude/settings.json
终端：mkdir -p ~/.claude && nano ~/.claude/settings.json
⚠ .claude 是隐藏文件夹（开头的点表示隐藏）— 默认看不到，要按上面的方法显示
env.ANTHROPIC_BASE_URL
https://<gateway-domain>
仅域名 · 不要追加 /v1/messages
env.ANTHROPIC_API_KEY
cap_xxxxxxxxxxxxxxxxxxxxxxxx
向管理员领取 · 每人一把
hasCompletedOnboarding
true
与 env 平级 · 跳过欢迎页探测
SCOPE 只想让某个项目走网关？把同样的 JSON 写到该项目根目录的 .claude/settings.local.json（自动 gitignore，不入仓），而不是全局。
settings.json — Claude Code
{} settings.json
.claude › {} settings.json 
 1  {
 2    "env": {
 3      "ANTHROPIC_BASE_URL": "https://<gateway-domain>",
 4      "ANTHROPIC_API_KEY": "cap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 5    },
 6    "hasCompletedOnboarding": true
 7  }
ready { } JSON UTF-8 LF Spaces: 2
avoid · 撞过的坑

装完先看这里
90% 的卡点就这几种

第一次跑 claude 命令最容易撞的是登录欢迎页一直转圈 — 不是网关问题，是 Claude Code 启动时会探 api.anthropic.com 校验账号，被墙时就卡住。下面先把这条说清楚。

Claude Code CLI stuck on launch
CLI · 终端里跑 claude 命令 → ERR_BAD_REQUEST / Unable to connect
VS Code Claude Code extension login screen
VS Code 扩展 · 一直停在 "How do you want to log in?"
卡欢迎页

Claude Code 首启卡在 onboarding · VS Code 扩展同样会卡

cause启动时仍会探 api.anthropic.com 校验账号。被防火墙挡住时一直转。 在 VS Code 扩展里则一直停留在登录页，点 Claude.ai Subscription / Anthropic Console 也无反应。
fix在 ~/.claude.json 顶层加一行（注意是文件，不是 .claude/ 目录）：
paste
{
  "hasCompletedOnboarding": true
}
path
macOS
/Users/你的用户名/.claude.json
终端：code ~/.claude.json · 或 Finder「前往 → 个人」+ ⌘+⇧+. 显示隐藏
Windows
C:\Users\你的用户名\.claude.json
PowerShell：notepad $env:USERPROFILE\.claude.json
Linux
/home/你的用户名/.claude.json
终端：touch ~/.claude.json && nano ~/.claude.json
⚠ 别搞混：这是 ~/.claude.json（家目录下的单个文件），不是 ~/.claude/settings.json（目录里的文件）— 名字几乎一样，路径不同
verify改完保存：CLI 重跑 claude，VS Code 重启扩展窗口 — 直接进交互模式 / 进入聊天界面即成。
Desktop 没生效

Claude Desktop Apply 后聊天仍走原账号

cause只关闭窗口，没真正退出。Apply 必须配合 Cmd+Q 完全退出再重启才会激活。
fixmacOS 用 Activity Monitor 确认 Claude 进程消失；Windows 用任务管理器。
401

invalid api key

causekey 拼错；服务端未登记；或在 Gateway URL 末尾追加了 /v1/messages。
fixGateway base URL 只填到域名（不带路径）；如仍 401，找管理员核对 key。
ENV

全局 export 污染常规 claude

cause把 ANTHROPIC_BASE_URL 写进 ~/.zshrc 后，本人原 Claude 订阅也跟着走代理。
fix只写进 ~/.claude/settings.json 的 env 字段（仅 claude 进程读取），不要 export 到 shell。
STILL STUCK? 把 claude --version 与 cat ~/.claude/settings.json 的输出（key 字段打码）发给管理员，比口述快十倍。
step 03 · claude desktop

桌面端走
Developer Mode GUI

Claude Desktop 不读 ~/.claude/settings.json。必须先在 Help 菜单里勾上 Developer Mode，再用 Developer 菜单弹出的 GUI 面板填 4 个字段。下方截图按真实顺序排列，逐图照做即可。

A

开启开发者模式

顶部菜单：Help → Troubleshooting → Enable Developer Mode。勾选后菜单栏会多出 Developer 项。

B

完全退出 Claude Desktop

Cmd+Q（macOS）/ 右键托盘 Quit（Windows / Linux）。仅关窗等于没退；新 Developer 菜单不会激活。

⌘+Q macOS：完全退出快捷键
C

Developer → Configure Third-Party Inference

弹出 Gateway 配置面板。按下表填四项，点 Apply locally。

Provider 顶部下拉，必选 Gateway（不是 Direct）
Gateway
Credential kind 下拉选 Static API key；不要 Helper / Interactive
Static API key
Gateway base URL 管理员给的网关域名；不要带 /v1/messages
https://<gateway-domain>
Gateway API key 管理员发的专属 key
cap_xxxxxxxxxxxxxxxxxxxxxxxxxx
Gateway auth scheme 下拉选 bearer，不要 basic / api-key
bearer
Custom inference headers 默认即可
（留空，不要 + Add header）
C·2 Models 子面板 · 必填 3 个模型 ID（漏一个聊天框就看不到那个模型）
⚠ 必填 · ID 一字不差 Model discovery 保持 ON（默认即是）。 然后在 Model list 下点 + Add，把下面 3 个模型 ID 加进去 — 顺序不影响功能，加哪个顺序都行；唯一会变的是 Claude Desktop 把列表中第一个当作"新会话默认"，所以推荐把 opus-4-8 放第一位。 但 ID 必须精准（带连字符、带版本号），错一个字符模型选择器会出空、聊天直接 4xx。
claude-opus-4-8
claude-sonnet-4-6
claude-haiku-4-5
⚠ opus 还要展开 opus-4-8 加进去之后，点行首的 › 把它展开，把 "Offer 1M-context variant" 拨成 ON（蓝色）。这样新会话才能用 1M token 上下文。 sonnet 与 haiku 不需要展开，保持默认即可。
D

再次完全退出 + 重启

Apply 后必须再 Cmd+Q 一次；不然聊天框仍走旧链路。重启完成后聊天即走网关。

✓ 重启后随便发一句问候。响应正常 = 接入成功。