AI 大模型网关

AI Model Gateway 在 Open4X 的鉴权、计费、日志、成本限制和连接账户体系后提供 OpenAI-compatible 模型接口。

支持的 Endpoint

所需 scope：

ai:invoke

POST /v1/apps/ai/:alias/chat
POST /v1/apps/ai/:alias/chat/completions
POST /v1/apps/ai/:alias/v1/chat/completions
POST /v1/apps/ai/:alias/chat/stream
POST /v1/apps/ai/:alias/embeddings
POST /v1/apps/ai/:alias/v1/embeddings

/chat/completions 和嵌套的 /v1/* 是 OpenAI-compatible 兼容路径，适合从 provider baseUrl 自动拼接路径的工具。

对于客户端可能自动重试的请求，建议设置 Idempotency-Key。同一用户重复使用同一个 key 会返回 409 idempotency_key_used，不会再次扣费或调用上游；新请求必须生成新的 key。key 长度为 1–128 个字符，只允许 A-Z a-z 0-9 . _ : -。

BYOK 模式

当前 MVP 支持 BYOK，也就是用户自带模型供应商 API Key。API Key 可以直接配置在 AI 服务实例中，也可以先保存为 Connected Account，再由服务实例引用。

支持的连接账户 provider：

openai-compatible
openrouter
deepseek
custom-api-key

服务配置

直接密钥模式会保存加密后的 provider key：

{
  "provider": "openai-compatible",
  "mode": "byok",
  "base_url": "https://api.openai.com/v1",
  "default_model": "gpt-4o-mini",
  "api_key_encrypted": "enc:v1:...",
  "max_tokens_per_request": 2048,
  "max_cost_per_request": 0.05,
  "timeout_ms": 30000,
  "fallback_aliases": ["backup"],
  "routing_policy": "manual",
  "log_requests": false
}

连接账户模式只保存引用：

{
  "provider": "openai-compatible",
  "mode": "byok",
  "connected_account_id": "conn_...",
  "base_url": "https://openrouter.ai/api/v1",
  "default_model": "anthropic/claude-sonnet",
  "max_tokens_per_request": 4096,
  "max_cost_per_request": 0.10,
  "timeout_ms": 30000,
  "fallback_aliases": ["backup"]
}

timeout_ms 默认 30 秒，范围限制为 250–120000 毫秒；它同时覆盖上游响应头超时，以及流式响应两个数据块之间的最大空闲时间。fallback_aliases 最多配置 3 个、且属于同一用户并已启用的 AI 服务 alias。只有网络错误、HTTP 408、429 或 5xx 才会切换备用服务；鉴权错误和请求参数错误不会自动重试。切换成功时，响应会带上 X-OpenEdge-Fallback-Alias。

routing_policy 默认为 manual。只有在 fallback 列表已经按“经过评测的强模型优先”排序后，才建议设置为 complexity_first。遇到通用数学/几何、调试、架构、合规、医疗、法律或金融等复杂度信号时，会先尝试 fallback，再尝试 primary；这只是显式开启的路由启发式，不是正确性保证。路由层只在内存中检查请求文本，不保存请求正文。

Console AI Playground 可以记录 metadata-only 评测结果。排行榜包含通过率、平均延迟、平均 token 用量和平均实际成本；prompt、评测标准、答案和 warning 文本留在浏览器，不会写入平台数据库。

Chat 示例

curl -X POST https://api.open4x.com/v1/apps/ai/default/chat \
  -H "X-API-Key: sk_xxx" \
  -H "Idempotency-Key: chat_req_20260808_001" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "把这段文字总结成三点。" }
    ],
    "max_tokens": 1000,
    "max_cost": 0.05
  }'

响应体保持上游 OpenAI-compatible 格式。账务信息通过响应头返回：

X-OpenEdge-Estimated-Cost: 0.0005
X-OpenEdge-Final-Cost: 0.0005
X-OpenEdge-Total-Tokens: 400

Streaming

curl -N -X POST https://api.open4x.com/v1/apps/ai/default/chat/stream \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "写一段发布说明。" }],
    "stream": true
  }'

Open4X 会转发供应商 SSE 流，并在流结束后结算 token 用量。如果上游没有返回 usage，则按预扣估算费用结算。

流式响应建立后只会先返回预估费用，最终费用不会追加到已经建立的 SSE 响应头中；需要在平台账单或用量记录中核对最终结算。

OpenAI-compatible 客户端也可以在标准 chat completions 路径上用 "stream": true 发起流式请求：

curl -N -X POST https://api.open4x.com/v1/apps/ai/default/v1/chat/completions \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "写一段发布说明。" }],
    "stream": true
  }'

OpenClaw

创建一个带 ai:invoke scope 的 API Key，然后在 OpenClaw 中添加自定义 OpenAI-compatible provider：

{
  "models": {
    "mode": "merge",
    "providers": {
      "openedge": {
        "baseUrl": "https://api.open4x.com/v1/apps/ai/qwen122/v1",
        "apiKey": "sk_xxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "mlx-community/Qwen3.5-122B-A10B-4bit",
            "name": "Qwen3.5 122B",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 131072,
            "maxTokens": 32768
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "models": {
        "openedge/mlx-community/Qwen3.5-122B-A10B-4bit": {
          "alias": "qwen122"
        }
      }
    }
  }
}

OpenClaw 会把 provider key 放在 Authorization: Bearer <apiKey>；Open4X 现在同时支持这种形式和 X-API-Key。

Embeddings

curl -X POST https://api.open4x.com/v1/apps/ai/default/embeddings \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["第一段文本", "第二段文本"],
    "max_cost": 0.02
  }'

计费

BYOK 模式下平台收取网关服务费：

final_cost = request_fee + total_tokens / 1,000,000 * token_gateway_fee

网关会在调用前检查余额，记录 estimated cost 和 final cost，并在最终成本低于预扣费用时退款。

安全

• Provider API Key 使用 CONFIG_ENCRYPTION_KEY 加密。
• 控制台不会返回明文 provider key。
• base_url 必须是 HTTPS，并通过 SSRF 防护。
• 默认日志只保存 provider、model、token usage、status、cost 和 latency，不保存 prompt 或完整 response。