订阅代理

订阅代理是一个本地 HTTP 服务器，让外部应用——OpenViking、Karakeep、Open WebUI，以及任何支持 OpenAI 兼容聊天补全（chat completions）的应用——能够将你的 AigenLabs 托管提供商订阅用作其 LLM 端点。代理会自动附加正确的凭据（并在需要时自动刷新），因此应用无需静态 API 密钥。

这与 API 服务器不同：

	API 服务器	订阅代理
服务内容	你的 Agent（完整工具集、记忆、技能）	原始模型推理
使用场景	"将 AigenLabs 用作聊天后端"	"从其他应用使用我的 Portal 订阅"
认证	你的 `API_SERVER_KEY`	任意 bearer（代理附加真实凭据）
工具调用	是——Agent 执行工具	否——仅透传

当你需要将 Agent 作为后端时，使用 API 服务器。当你只需要通过订阅访问模型时，使用代理。

快速开始

1. 登录你的提供商（仅需一次）

aigenlabs portal

这会打开浏览器进行 Nous Portal OAuth 流程。AigenLabs 将刷新令牌存储在 ~/.aigenlabs/auth.json 中——与所有 AigenLabs 提供商登录信息存放在同一位置。

2. 启动代理

aigenlabs proxy start

Starting AigenLabs proxy for Nous Portal
  Listening on:  http://127.0.0.1:8645/v1
  Forwarding to: (resolved per-request from your subscription)
  Use any bearer token in the client — the proxy attaches your real credential.

保持在前台运行。如需在注销后继续运行，请使用 tmux、nohup 或 systemd 单元。

3. 将你的应用指向代理

任何 OpenAI 兼容应用的配置都使用相同的三元组：

Base URL:   http://127.0.0.1:8645/v1
API key:    任意值（例如 "sk-unused"）
Model:      Hermes-4-70B    # 或 Hermes-4.3-36B、Hermes-4-405B

代理会忽略来自你应用的 Authorization 请求头，并将你真实的 Portal 凭据附加到上游请求中。当 bearer 令牌临近过期时，刷新会自动进行。

可用提供商

aigenlabs proxy providers

当前已内置：nous（Nous Portal）。更多 OAuth 提供商可通过在 aigenlabs_cli/proxy/adapters/ 中实现 UpstreamAdapter 接口来添加。

检查状态

aigenlabs proxy status

AigenLabs proxy upstream adapters

  [nous    ] Nous Portal — ready (bearer expires 2026-05-15T06:43:21Z)

如果显示 not logged in，请运行 aigenlabs portal。如果显示 credentials need attention，说明你的刷新令牌已被撤销（较少见——通常发生在你从 Portal Web UI 退出登录时）——重新运行 aigenlabs portal 即可。

允许的路径

代理仅转发上游实际提供的路径。对于 Nous Portal：

路径	用途
`/v1/chat/completions`	聊天补全（流式与非流式）
`/v1/completions`	旧版文本补全
`/v1/embeddings`	Embeddings（嵌入）
`/v1/models`	模型列表

其他路径（/v1/images/generations、/v1/audio/speech 等）将返回 404，并附带明确的错误信息指向允许的路径。这可防止游离客户端向上游发送异常请求。

配置 OpenViking 使用 Portal

OpenViking 是一个上下文数据库，需要 LLM 提供商来支持其 VLM（用于提取记忆的视觉/语言模型）和 embedding 模型。通过代理，你可以将其 vlm.api_base 指向本地代理：

编辑 ~/.openviking/ov.conf：

{
  "vlm": {
    "provider": "openai",
    "model": "Hermes-4-70B",
    "api_base": "http://127.0.0.1:8645/v1",
    "api_key": "unused-proxy-attaches-real-creds"
  }
}

然后在终端中与 openviking-server 一起启动代理：

# 终端 1
aigenlabs proxy start

# 终端 2
openviking-server

OpenViking 的 VLM 调用现在将通过你的 Portal 订阅进行。Embedding 模型侧仍需要自己的提供商——Portal 确实提供 /v1/embeddings，但模型选择取决于你的套餐所支持的内容；请查看 portal.nousresearch.com/models。

配置 Karakeep（或任何书签/摘要应用）

Karakeep 使用 OpenAI 兼容 API 进行书签摘要。在其配置中：

# Karakeep .env
OPENAI_API_BASE_URL=http://127.0.0.1:8645/v1
OPENAI_API_KEY=any-non-empty-string
INFERENCE_TEXT_MODEL=Hermes-4-70B

同样的方式适用于 Open WebUI、LobeChat、NextChat 或任何其他 OpenAI 兼容客户端。

在局域网上暴露

默认情况下，代理绑定 127.0.0.1（仅限本机）。若要让网络中的其他机器使用：

aigenlabs proxy start --host 0.0.0.0 --port 8645

⚠ 注意： 你网络中的任何人现在都可以使用你的 Portal 订阅。代理本身没有认证机制——它接受任意 bearer。如果你将其暴露在可信网络之外，请使用防火墙、VPN 或带有适当认证的反向代理。

速率限制

你的 Portal 套餐的 RPM/TPM 限制适用于整个代理。代理不进行扇出或连接池——它是单个 bearer，使用你的完整订阅配额。请在 portal.nousresearch.com 监控使用情况。

架构

代理设计上尽量精简。每个请求的处理流程：

从你的应用接收 POST /v1/chat/completions
查找适配器的当前凭据（如临近过期则刷新）
原样转发请求体，附加 Authorization: Bearer <minted-key>
将响应原样流式返回（SSE 保持不变）

无转换。不记录请求体。无 Agent 循环。代理是一个附加凭据的透传通道。

未来：更多 OAuth 提供商

适配器系统是可插拔的。添加新提供商（例如 HuggingFace、GitHub Copilot 的聊天端点、通过 OAuth 接入的 Anthropic）需要在 aigenlabs_cli/proxy/adapters/<provider>.py 中实现 UpstreamAdapter，并在 adapters/__init__.py 中注册。协议层面不兼容 OpenAI 的提供商（例如 Anthropic Messages API）需要额外的转换层，这超出了当前版本的范围。

快速开始​

1. 登录你的提供商（仅需一次）​

2. 启动代理​

3. 将你的应用指向代理​

可用提供商​

检查状态​

允许的路径​

配置 OpenViking 使用 Portal​

配置 Karakeep（或任何书签/摘要应用）​

在局域网上暴露​

速率限制​

架构​

未来：更多 OAuth 提供商​