部署 sub2api 并对接 OpenClaw：统一中转 API 入口实践

背景：为什么需要统一的中转 API 入口

在多模型、多供应商并行的使用场景中，如果把不同 API 分散配置到各个工具里，往往会带来这些问题：配置复杂、切换成本高、密钥分散难管理、限流与审计难统一。建立一个统一的中转入口，可以把“上游模型供应商”与“下游应用”解耦，从而降低维护成本。

本篇将通过部署 sub2api，并将 OpenClaw 的 OpenAI 兼容 API Base URL 指向 sub2api，实现统一入口与集中控制。

原理：sub2api 作为统一入口的工作方式

sub2api 处在应用与上游模型之间，负责请求转发、统一鉴权、地址聚合与策略控制。对下游（OpenClaw）而言，只需要对接一个 OpenAI 兼容的 Base URL；对上游而言，可以灵活接入多个 Provider，并在中转层做统一管理。

架构示意（文字图）

App / OpenClaw
      |
      |  OpenAI-compatible API
      v
   sub2api
      |
      +-- Provider A
      +-- Provider B
      +-- Provider C

部署 sub2api

使用 kejilion.sh 一键部署：

bash <(curl -sL kejilion.sh) app sub2api

部署完成后，请记录 sub2api 的访问地址与鉴权信息（如 API Key/令牌等），后续用于 OpenClaw 对接。并且记得在 sub2api 后台把分组、上游账户、API Key 等配置完善；如果是给用户分发使用，还需要为用户设置充值额度/余额，否则会因为余额不足导致无法调用。

部署 OpenClaw

同样使用 kejilion.sh 一键部署：

bash <(curl -sL kejilion.sh) app OpenClaw

确保 OpenClaw 服务正常启动，并具备对外访问能力（至少 OpenClaw 到 sub2api 的网络要通）。

OpenClaw 对接 sub2api（核心配置）

核心思路：把 OpenClaw 的 OpenAI 兼容 API Base URL 指向 sub2api。你可以用“手动配置”（两种常见写法如下），也可以用 kejilion.sh 的 OpenClaw 管理工具做一键接入与批量维护。

方式一：环境变量（推荐用于容器或 systemd 服务）

# OpenClaw 环境变量示例（占位符请替换）
OPENAI_API_BASE=https://your-sub2api.example.com/v1
OPENAI_API_KEY=your-sub2api-key

方式二：配置文件写法（示例占位符）

# config.yaml / app.yml 中的示例片段（字段名按你实际配置文件为准）
openai:
  api_base: "https://your-sub2api.example.com/v1"
  api_key: "your-sub2api-key"

方式三：使用 kejilion.sh 的 OpenClaw 管理工具（推荐）

如果你希望轻松配置 API，并且后续需要批量导入模型、批量同步模型一致性、批量管理模型（启用/禁用/统一命名等），建议直接使用 kejilion.sh 内置的 OpenClaw 管理工具统一完成接入与维护。

配置完成后，重启 OpenClaw 服务，确保新配置生效。

验证步骤

验证的目标是确认：OpenClaw 能通过 sub2api 正常请求到上游模型，并且返回结果正确。

1. 在 OpenClaw 中触发一次 OpenAI 兼容调用（例如一次对话/补全请求）。
2. 检查 sub2api 的日志或控制台，确认收到来自 OpenClaw 的请求。
3. 确认请求能得到正常响应，并观察延迟与错误率是否合理。

如果验证失败，优先排查 Base URL 是否写对（尤其是 /v1 路径）、API Key 是否一致、OpenClaw 到 sub2api 的网络连通性、反向代理/防火墙是否拦截。

常见问题排查

1）OpenClaw 返回 401/403
一般是 API Key 不一致、未生效或 sub2api 有额外鉴权规则。建议核对 OpenClaw 的 KEY 与 sub2api 端的鉴权配置，并确认重启后已加载新环境变量/配置。

2）请求超时或无响应
检查 sub2api 是否可达、上游 Provider 是否可用、端口/防火墙/Nginx 反代是否放行，以及是否存在 DNS/证书导致的连接失败。

3）模型名称不匹配或返回“模型不存在”
确认 sub2api 的模型映射是否正确；如果 sub2api 需要将下游模型名映射到上游模型名，确保映射表已配置并生效。

安全建议

1）为 sub2api 设置强口令或强度足够的 API Key，避免公开暴露后被滥用。

2）启用 HTTPS，并在反向代理层增加访问控制与限流（例如仅允许特定来源 IP 访问）。

3）密钥建议放在环境变量或安全配置中，避免在文章截图、公开仓库或日志中泄露明文。

4）开启访问日志与审计，便于问题追踪、调用统计与费用核算。

总结

通过部署 sub2api 并将 OpenClaw 的 OpenAI 兼容 API Base URL 指向 sub2api，你可以把多上游模型的差异隐藏在中转层，实现统一入口、集中管理与更高可维护性。对于多模型、多供应商并行的使用环境，这套方案能显著降低配置复杂度与运维成本。