Agent On
quickstart · 5 分钟

接入 Agent On

按客户端分两条配置线：Claude 写 ~/.claude/settings.json，Codex 写 ~/.codex/config.toml。只改本机客户端入口，不改业务代码。

开始配置 ↓ 下载桌面端
向管理员领取 API Key · 每人一把
CLAUDE PATH ~/.claude/settings.json 
1{
2  "env": {
3    "ANTHROPIC_BASE_URL": "https://<gateway-domain>",
4    "ANTHROPIC_API_KEY": "cap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
5  },
6  "hasCompletedOnboarding": true
7}
01
客户端
Claude / Codex · CLI 与桌面端
02
配置文件
~/.claude + ~/.codex
03
业务代码
一行都不用改
04
停机
随时切换，不中断

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

Claude 生态与 Codex 生态各有自己的客户端配置文件。下面先装客户端；下一步会分开写 ~/.claude/settings.json 与 ~/.codex/config.toml 的真实写法。

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。配置一次到处通用。

安装命令
code --install-extension anthropic.claude-code
03
Codex CLI / Desktop
config.toml · /v1 responses

Codex 生态走 ~/.codex/config.toml，base_url 指向网关 /v1，wire_api 用 responses；Desktop 同理走 /v1 网关入口。

安装命令
codex
TIP 如果你不想手动改配置文件，直接去 下载 Agent On 桌面端。它会帮你一键配置 Claude 与 Codex；想自己掌控细节，再按本页手动配置即可。

Claude 写 settings.json
Codex 写 config.toml

左边规则先记住：Claude 生态只改 ~/.claude/settings.json；Codex 生态只改 ~/.codex/config.toml。 右侧上半块是 Claude 配置，下半块是 Codex 配置。把 <gateway-domain> 与管理员给你的 key 换进去即可。 Claude 侧的 hasCompletedOnboarding 必须与 env 平级，不要写到 env 里面。

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
CODEX PATH ~/.codex/config.toml 
1model = "gpt-5-codex"
2model_provider = "codex-api"
3
4[model_providers.codex-api]
5name = "codex-api"
6base_url = "https://<gateway-domain>/v1"
7wire_api = "responses"
8env_key = "CODEX_API_KEY"

装完先看这里
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 字段打码）发给管理员，比口述快十倍。

桌面端走
Developer Mode GUI

Claude Desktop 不读 ~/.claude/settings.json。必须先在 Help 菜单里勾上 Developer Mode，再用 Developer 菜单弹出的 GUI 面板填 4 个字段。若你想省掉这些手工步骤，可直接去 下载 Agent On 桌面端 做一键配置。

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 一次；不然聊天框仍走旧链路。重启完成后聊天即走网关。

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