个人与企业如何接入大模型网关及配套 CLI

作者：袖梨 2026-09-14

在多个模型供应商和编程客户端之间切换时，接口路径、鉴权方式与模型名称往往各不相同，稍有配置偏差就可能出现请求失败。通过统一的大模型网关，可以集中处理密钥分发、用量追踪和协议转换。下面将从地址填写规则入手，梳理常用客户端与配套 CLI 的接入、验证及排错要点。

目前我的网关服务（鉴权 用量追踪 sk虚拟分发 支持OpenAi和Anthropic标准化自动编程） 配套的CLI和web UI 操作功能已经可以正式投入使用（支持对话和任务模式）

  • 网关服务：github.com/boonya-hrgk…
  • CLI服务：github.com/boonya-hrgk…

接入网关

本网关对外提供 OpenAI 兼容 的 /v1/* 接口，并内置 Anthropic ↔ OpenAI 方言翻译，因此 Claude Code、CC Switch、OpenCode 以及各类 OpenAI 客户端都能直接接入。

客户端按各自 SDK 的约定拼接请求路径，所以两种方言要填的地址不一样。下方每个客户端段落都标注了它属于哪一种：

网关地址http://192.168.5.34:9000复制

OpenAI 方言http://192.168.5.34:9000/v1复制

OpenCode / DeepSeek Harness / 各类 OpenAI SDK。地址必须带 /v1——这些 SDK 只会再拼 /chat/completions，漏了会返回 405。

Anthropic 方言http://192.168.5.34:9000复制

Claude Code / CC Switch。地址不要带 /v1——这些 SDK 会自己拼 /v1/messages。

健康检查curl http://192.168.5.34:9000/health测试

✓ 网关正常（默认上游可达）

三步快速接入

  1. 获取密钥：管理员在「授权管理 → 密钥管理」创建 sk- 密钥并绑定上游；普通用户由管理员分配，可在「对话测试」页选择自己的密钥查看。
  2. 配置地址：Base URL 填网关地址 http://192.168.5.34:9000（OpenAI 兼容端点路径为 /v1，Anthropic 方言直接填根地址）。
  3. 调用测试：用下方 curl 验证，或把配置写入你的客户端工具。

通用 OpenAI 兼容客户端

OpenAI 方言

任意支持 OpenAI 协议的客户端。把 base_url 指向 http://192.168.5.34:9000/v1（必须带 /v1：SDK 只会再拼 /chat/completions），api_key 填网关发放的 sk- 密钥即可。

复制

curl http://192.168.5.34:9000/v1/chat/completions 
  -H "Authorization: Bearer sk-你的密钥" 
  -H "Content-Type: application/json" 
  -d '{"model":"你的模型名","messages":[{"role":"user","content":"你好"}],"stream":true}'

Claude Code 接入

Anthropic 方言

Claude Code 走 Anthropic 协议（请求路径 /v1/messages），网关会自动把请求翻译到绑定上游（OpenAI / Ollama / vLLM 等）。ANTHROPIC_BASE_URL 填网关根地址，不要带 /v1——SDK 会自己拼上。模型名填上游真实模型名即可。

复制

# 网关地址与鉴权（必需）
export ANTHROPIC_BASE_URL="http://192.168.5.34:9000"
export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"

# 模型映射：Claude 模型名 → 上游真实模型名
export ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"

# 关闭非必要流量上报
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"

CC Switch 接入

Anthropic 方言

CC Switch 可在多个供应商间一键切换。把网关作为 Anthropic 供应商添加：ANTHROPIC_BASE_URL 填网关根地址（不要带 /v1，环境变量同 Claude Code），即可在 Claude Code 等客户端里切换本地 / 云端模型。

DeepSeek 云端模型

复制

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.5.34:9000",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

本地 Ollama 模型

复制

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://192.168.5.34:9000",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_MODEL": "qwen3:8b",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3:8b-nothink",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3:8b-nothink",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "qwen3:8b-nothink",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

OpenCode 接入

OpenAI 方言

OpenCode 通过 OpenAI 兼容 Provider 指向网关，Provider 的 baseURL 填 http://192.168.5.34:9000/v1（必须带 /v1）。写好后运行 opencode auth login 选择 gateway 并粘贴 sk- 密钥（或设置 OPENAI_API_KEY 环境变量）。

复制

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LLM API Gateway",
      "options": {
        "baseURL": "http://192.168.5.34:9000/v1"
      },
      "models": {
        "deepseek-v4-pro[1m]": { "name": "DeepSeek V4 Pro" }
      }
    }
  }
}

DeepSeek Harness 接入

OpenAI 方言

dsh 通过自定义 Provider 接入网关，走 OpenAI 方言：api 填 openai-completions，baseURL 填 http://192.168.5.34:9000/v1（必须带 /v1）。在 Web UI 右上角点「打开配置文件」，编辑 ~/.dsh/settings.yaml（Windows 为 C:Users<用户名>.dshsettings.yaml），加入下面两块即可。密钥不写进 yaml——apiKeyEnv 只是引用名，真实密钥用环境变量注入，这也符合网关「上游 Key 不外泄」的口径。

复制

llm-pi-ai:
  providers:
    {
      llm-api-gateway:
        {
          displayName: llm-api-gateway,
          apiKeyEnv: LLM_API_GATEWAY_API_KEY,
          api: openai-completions,
          baseURL: http://192.168.5.34:9000/v1,
          models:
            [
              { id: deepseek-v4-flash, name: deepseek-v4-flash },
              { id: deepseek-v4-pro, name: deepseek-v4-pro }
            ]
        }
    }
agent-default-model:
  provider: llm-api-gateway
  model: deepseek-v4-flash

复制

# 密钥用环境变量注入，不要写进 settings.yaml
export LLM_API_GATEWAY_API_KEY="sk-你的密钥"
npx @deepseek-ai/dsh web

看到 405 Method Not Allowed 就是 baseURL 漏了 /v1——请求会落到 /chat/completions 被静态页面接住；这种错法不会返回 401，别去查密钥。

配套 CLI 测试工具

OpenAI 方言Anthropic 方言

配套仓库 llm-api-gateway-cli 用于验证网关除 Web 页面外命令行同样可用。六种模式横跨两种方言，其中原生 Agent（模式六）是终端里干活的推荐方式——自带工具循环，无需安装 Claude Code。

.env 里的 GATEWAY_BASE_URL 填网关根地址（不要带 /v1）——脚本会按方言自己拼：OpenAI 模式的脚本补 /v1，Anthropic 模式的脚本直接用根地址。

安装

复制

git clone https://github.com/boonya-hrgk/llm-api-gateway-cli.git
cd llm-api-gateway-cli
npm install

cp .env.example .env   # 再按下面内容编辑 .env

复制

# .env —— 网关根地址（不要带 /v1，脚本会按方言自己拼）
GATEWAY_BASE_URL=http://192.168.5.34:9000
GATEWAY_KEY=sk-你的密钥
GATEWAY_MODEL=deepseek-v4-flash

六种模式

模式脚本方言走网关的端点
一 · OpenAI 兼容cli-openai.jsOpenAI/v1/chat/completions
二 · Anthropic 兼容cli-anthropic.jsAnthropic/v1/messages
三 · Claude Codecli-claude-code.jsAnthropic/v1/messages
四 · 本地聊天 Web UIserver.jsOpenAI/v1/chat/completions
五 · 任务模式（真读写目录）task-server.jsOpenAI/v1/chat/completions + 工具调用
六 · 原生 Agent CLI（推荐）cli-agent.jsOpenAI/v1/chat/completions + 工具调用

常用命令

复制

npm link                       # 装成全局命令，之后在任意目录可用

llm-api-gateway-cli            # 模式六：原生 Agent 交互，当前目录即工作目录
llm-api-gateway-cli -p "总结这个项目"    # 模式六：单轮任务（写入前会确认）
gateway-claude-code            # 模式三：进入 Claude Code（需本机已装 claude）
gateway-web                    # 模式四：本地聊天页 http://127.0.0.1:3100
gateway-task                   # 模式五：任务模式 http://127.0.0.1:3101

健康检查

用于确认网关与默认上游是否可达：

复制

curl -i http://192.168.5.34:9000/health

# 默认上游可达 → 200
#   HTTP/1.1 200 OK
#   {"status":"ok"}

# 默认上游连不上 → 502（注意：网关进程本身仍是好的）
#   HTTP/1.1 502 Bad Gateway
#   {"detail":"上游未就绪"}

注意：/health 只探测默认上游。它返回 502 的含义是「网关进程正常，但默认上游连不上」，不等于网关故障——你的密钥绑定的可能是另一个上游，照样能用。要确认自己那把密钥通不通，直接发一次真实请求最准。

另外两个探针：/health/live（进程存活）、/health/ready（数据库与可选 Redis 就绪）——未就绪时返回 503。 常见问题见下方「错误码速查」与项目 README 的「常见问题」章节。

错误码速查

网关自身的报错都是 {"detail": "..."} 结构（405 除外——那是请求路径没匹配上代理路由、由静态页面返回的）。上游自己的错误会原样透传，网关不改写状态码与响应体——所以看到 404 model not found 这类，是上游在报，不是网关。

状态码detail 文案含义与处理
401无效的 API Key不是网关发放的 sk- 密钥（例如填了上游真实 Key，或复制不完整）
401API Key 已被吊销密钥已吊销，换一把
401API Key 已过期超过设置的过期时间，到「密钥管理」调整或换密钥
400模型不可用：'xxx' 不在该密钥所绑定上游（…）的可用模型并集内模型准入拦截；这条文案后面会直接列出当前可用的模型
400请求体不是合法 JSON请求体格式错，检查 JSON
400上游为 Anthropic 方言（…），不支持 /v1/embeddings该密钥绑的上游是 Anthropic 方言，没有这个端点
429请求过于频繁，请稍后再试触发限流，按 Retry-After 秒数后重试
429token 配额已用尽（今日/本周/本月），将于配额周期重置后恢复超 token 配额，同上
429金额配额已用尽（今日/本周/本月），将于配额周期重置后恢复超金额配额，同上
502未找到可用的上游配置密钥没绑定任何上游，到「密钥管理」绑定
502上游请求失败，请稍后重试网关连不上下游；真实原因在网关日志里（刻意不向前端暴露上游地址）
405（无 JSON 请求体，返回纯文本）base_url 漏了 /v1，见上方各客户端段落

带 429 的响应会附 Retry-After 响应头（单位：秒），照它等待后重试即可。被网关拦下的 401 / 400 / 429 请求不计入调用次数、也不产生费用——网关只对真正放行到上游的请求记账。

参考文档

  • CC Switch 官网
  • CC Switch 使用教程（一聚小编教程）
  • Claude Code 使用教程（一聚小编教程）
  • OpenCode 编码 Agent 教程（一聚小编教程）
  • DeepSeek Harness 保姆级安装与使用教程！
  • 配套 CLI 测试工具 llm-api-gateway-cli

相关文章

精彩推荐