公开指南

启用 AI Gateway 和 AI 提供商连接

将 `/ai-gateway` 作为设置中心：连接一个 BYOK 提供商密钥，在策略中将其加入允许列表，然后为您的 IDE 或自动化工具创建一个客户端。 受众: 租户管理员、安全主管和工作区所有者. 典型配置时长: 15-20 分钟.

reference

适用场景

将 `/ai-gateway` 作为设置中心：连接一个 BYOK 提供商密钥，在策略中将其加入允许列表，然后为您的 IDE 或自动化工具创建一个客户端。

目标受众: 租户管理员、安全主管和工作区所有者预计耗时: 15-20 分钟

开始之前

  • 选择您想要试点的第一个提供商、IDE 或自动化工作流程。
  • 确认允许用户查看哪些提供商标识和 MCP 工具。
  • 在创建访问权限之前，备齐回调 URL 或客户端配置详细信息。

操作指引

1

步骤 1

首先连接一个提供商

从 `/ai-gateway` 开始，然后打开 OpenAI 提供商连接以添加您的团队已经信任的第一个租户自有密钥。

  • 除非您的试点明确需要 Anthropic 或 OpenAI 兼容端点，否则请使用 `/integrations/ai_openai` 获取第一个 BYOK 提供商凭据。
  • 为 BlackShield 使用专用的提供商密钥，而不是在人际共享的个人密钥。
  • 在返回 AI Gateway 之前运行提供商预检。

达成目标状态

在返回 AI Gateway 之前运行提供商预检。

2

步骤 2

在策略中将提供商列入允许列表

在策略显式允许连接的提供商之前，AI Gateway 会限制活动的路由和访问。

  • 从 `/ai-gateway` 打开策略选项卡，并将连接的提供商添加到 `approved_providers`。
  • 保持第一条策略简单明了：提供商允许列表、隐藏工具和明确的请求限制。
  • 保持咨询模式 (advisory)，直到试点团队看到您预期的警告，然后再转为强制执行 (enforce)。

达成目标状态

保持咨询模式 (advisory)，直到试点团队看到您预期的警告，然后再转为强制执行 (enforce)。

3

步骤 3

为您团队使用的工具创建客户端

为每个 IDE、MCP 客户端或服务主体分配其专用的 AI Gateway 客户端，以便轻松轮换或禁用访问权限。

  • 为登录流程创建公共客户端，或为无头自动化创建机密客户端。
  • 在将客户端移交给最终用户之前，添加您的 IDE 或 Agent 所需的回调 URL。
  • 将每个客户端限制在团队实际需要的提供商连接和 MCP 工具范围内。

达成目标状态

将每个客户端限制在团队实际需要的提供商连接和 MCP 工具范围内。

4

步骤 4

在广泛推广之前测试网关

首先运行一次低风险测试，以确认身份验证、策略行为和活动日志记录。

  • 将 MCP 端点设置为 `/api/v1/mcp`，将推理端点设置为 `/api/v1/ai-gateway/openai/v1/chat/completions`。
  • 使用新客户端登录或用客户端凭据换取短期令牌。
  • 运行 `tools/list` 或简单的只读提示词，然后确认该事件出现在 AI Gateway 活动流中。
  • 在邀请更多用户之前，审查策略警告和使用日志。

达成目标状态

在邀请更多用户之前，审查策略警告和使用日志。

Demonstration only

This configuration is designed for ease of use. To deploy scanner clients at scale, please plan your deployment architecture accordingly or contact us for enterprise best practices.

运行命令

Exchange client credentials for a short-lived token
curl -X POST https://api.blackshield.chaplau.com/api/v1/ai-gateway/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'
Query OpenAI completions via the Gateway Proxy
curl -X POST https://api.blackshield.chaplau.com/api/v1/ai-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer <your_short_lived_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "List the security requirements for the tenant onboarding flow."
      }
    ]
  }'
Configure the Stdin/Stdout MCP Proxy in Cursor / VS Code / Claude Desktop
{
  "mcpServers": {
    "blackshield-gateway": {
      "command": "blackshield-mcp",
      "args": [
        "--client-id", "<your-client-id>",
        "--client-secret", "<your-client-secret>",
        "--url", "https://api.blackshield.chaplau.com/api/v1/mcp"
      ]
    }
  }
}

达成目标状态

  • 试点客户端成功通过身份验证，并且仅能看到规划中的提供商和工具。
  • 活动流中显示测试调用以及任何预期的策略警告或拦截记录。
启用 AI Gateway 和 AI 提供商连接 | BlackShield Docs