沙盒认证代理 - Docs by LangChain中文

认证代理允许沙盒代码调用外部 API（OpenAI、Anthropic、GitHub 等）而无需硬编码凭据。当在沙盒上配置后，代理边车会自动使用您的工作区密钥或您在代理配置中提供的写入专用凭据，将认证头注入匹配的出站请求中。

您必须在创建引用这些密钥的沙盒之前，在您的 LangSmith 工作区设置中配置您的密钥（例如，OPENAI_API_KEY）。

出口流量与网络访问控制

用于注入凭据的同一个 proxy_config 也控制着沙盒可以访问哪些目标地址。

默认出口策略

默认情况下（未配置 access_control）：

允许到任何主机的 HTTP 和 HTTPS（端口 80 和 443）。 出站 HTTP(S) 请求会被透明地通过代理路由，您的 rules 和 callbacks 在此过程中注入凭据。
所有其他原始 TCP 流量被阻止。 除非您明确允许，否则到非 HTTP 端口的连接——数据库（5432 端口的 psql/dbt）、SSH (22)、Redis (6379) 等——将被丢弃。

这意味着原始协议被阻止并非因为代理”无法识别”它们——它们默认被阻止，并通过 access_control 按主机和端口开放。

允许列表和拒绝列表

在 proxy_config 中添加一个 access_control 对象，使用仅 allow_list 或 deny_list 之一（不能同时设置两者——如果同时设置，请求将被拒绝）：

模式	行为
`allow_list`	默认拒绝。只有列出的目标地址是可达的——包括 HTTP/HTTPS。如果您设置了 `allow_list`，还必须列出沙盒需要访问的每个 HTTP(S) 主机。
`deny_list`	默认允许 HTTP/HTTPS。除了列出的主机外，所有 HTTP(S) 主机保持可达。`deny_list` 无法开放原始 TCP 端口。

原始 TCP 出口（例如 5432 端口的 PostgreSQL）只能通过指定了明确非 HTTP 端口（host:PORT）的 allow_list 条目来启用。默认策略和 deny_list 模式仅允许 HTTP/HTTPS。

模式语法

每个 allow_list/deny_list 条目使用以下形式：

模式	含义
`host`	裸主机名 → 仅限端口 80 和 443 (HTTP/S)。
`host:PORT`	指定 `PORT` 的主机。`:22` 仅授予 22 端口，不会与 80/443 累加——如果需要同时允许两者，需要列出两次主机。
`*.example.com`	通配符（RFC 1034 风格）。不包含根域名（`example.com`）。
`~regex`	不透明的正则表达式匹配；无端口后缀解析。
`1.2.3.4` / `10.0.0.0/8`	字面 IP 或 CIDR。CIDR 不能携带端口（允许模式下仅限 HTTP/S；拒绝模式下阻止所有端口）。
`[::1]:22`	当指定端口时，IPv6 字面量使用带括号的形式。

连接数据库（原始 TCP）

要让沙盒代码通过 psql、dbt 或任何驱动程序访问外部 PostgreSQL 数据库，请将主机及其端口添加到允许列表。因为 allow_list 默认拒绝，所以还需要列出沙盒需要的任何 HTTP(S) 主机：

curl -X POST "$LANGSMITH_ENDPOINT/v2/sandboxes/boxes" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "db-sandbox",
    "wait_for_ready": true,
    "proxy_config": {
      "access_control": {
        "allow_list": [
          "db.example.com:5432",
          "api.openai.com"
        ]
      }
    }
  }'

到 db.example.com:5432 的连接在 TCP 层透传，不会被拦截，因此 PostgreSQL 线路协议——以及 TLS、主机密钥检查和其上的任何其他端到端协议——可以正常工作。

通过 SDK 配置

from langsmith.sandbox import SandboxClient

client = SandboxClient()

client.create_sandbox(
    name="db-sandbox",
    proxy_config={
        "access_control": {
            "allow_list": ["db.example.com:5432", "api.openai.com"]
        }
    },
)

import { SandboxClient } from "langsmith/sandbox";

const client = new SandboxClient();

await client.createSandbox({
  name: "db-sandbox",
  proxyConfig: {
    access_control: {
      allow_list: ["db.example.com:5432", "api.openai.com"],
    },
  },
});

配置认证代理规则

在创建沙盒时添加 proxy_config，或者通过修补现有沙盒的 proxy_config 来更新。每条规则指定：

字段	描述
`match_hosts`	要拦截的主机（支持如 `*.github.com` 的通配符）
`match_paths`	要匹配的路径（空值表示所有路径）
`headers`	要注入的头，每个头包含 `name`、`type` 和 `value`
`no_proxy`	完全绕过代理的主机（例如 `localhost`）

头类型

每个头都有一个 type，控制其值的存储和显示方式：

类型	描述
`workspace_secret`	使用 `{KEY}` 语法引用工作区密钥。在应用代理配置时解析。
`plaintext`	值按原样存储和返回。用于非敏感头。
`opaque`	写入专用。值在静态存储时加密，且永不通过 API 返回。

认证 AWS 请求

当沙盒代码需要使用 AWS SDK 或 CLI 调用 AWS 服务时，请使用 AWS 认证规则。代理将真正的 AWS 凭据保留在沙盒外部，然后使用 AWS SigV4 对支持的出站 HTTPS 请求进行签名。当代理代码需要检查 S3 对象、调用 Bedrock 或使用另一个支持的 AWS HTTPS 端点，而又不想在沙盒文件、环境变量、shell 历史记录或日志中暴露长期有效的 AWS 访问密钥时，这非常有用。沙盒会收到兼容性 AWS 凭据占位符，以便 SDK 凭据检测正常工作，而代理则使用配置的凭据对出站请求进行签名。

不要将真实的 AWS 访问密钥设置为沙盒环境变量。请将它们配置为 workspace_secret 或 opaque 代理值。纯文本 AWS 凭据值会被拒绝。

AWS 认证规则与头注入规则不同：

将 type 设置为 aws。
将凭据放在 aws 对象下。
不要设置 match_hosts、match_paths 或 headers；AWS 主机匹配内置于代理中。
每个沙盒最多配置一个 AWS 认证规则。

curl -X POST "$LANGSMITH_ENDPOINT/v2/sandboxes/boxes" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aws-sandbox",
    "wait_for_ready": true,
    "proxy_config": {
      "rules": [
        {
          "name": "aws",
          "type": "aws",
          "enabled": true,
          "aws": {
            "access_key_id": {
              "type": "workspace_secret",
              "value": "{AWS_ACCESS_KEY_ID}"
            },
            "secret_access_key": {
              "type": "workspace_secret",
              "value": "{AWS_SECRET_ACCESS_KEY}"
            }
          }
        }
      ]
    }
  }'

通过 SDK 配置 AWS 认证

from langsmith.sandbox import (
    SandboxClient,
    aws_auth,
    proxy_config,
    workspace_secret,
)

client = SandboxClient()

client.create_sandbox(
    name="aws-sandbox",
    proxy_config=proxy_config(
        rules=[
            aws_auth(
                access_key_id=workspace_secret("AWS_ACCESS_KEY_ID"),
                secret_access_key=workspace_secret("AWS_SECRET_ACCESS_KEY"),
            )
        ]
    ),
)

import {
  SandboxClient,
  awsAuth,
  proxyConfig,
  workspaceSecret,
} from "langsmith/sandbox";

const client = new SandboxClient();

await client.createSandbox({
  name: "aws-sandbox",
  proxyConfig: proxyConfig({
    rules: [
      awsAuth({
        accessKeyId: workspaceSecret("AWS_ACCESS_KEY_ID"),
        secretAccessKey: workspaceSecret("AWS_SECRET_ACCESS_KEY"),
      }),
    ],
  }),
});

沙盒就绪后，可在沙盒内正常使用 AWS SDK 或 CLI。SDK 或 CLI 可以发现占位符 AWS 环境变量，代理则将真实的 SigV4 签名应用于出站 AWS 请求。

AWS 认证代理规则目前支持访问密钥 ID 和秘密访问密钥凭据。它们不包括会话令牌或角色代入配置。

认证 GCP 请求

当沙盒代码需要使用 Google SDK 或 CLI 调用 Google API 时，请使用 GCP 认证规则。代理将服务账号 JSON 保留在沙盒外部，然后对沙盒代理匹配的 Google API 主机的受支持出站 HTTPS 请求进行身份验证。当代理代码需要检查 GCS 对象或调用另一个 Google API，而又不想在沙盒文件、环境变量、shell 历史记录或日志中暴露服务账号 JSON 时，这非常有用。沙盒会收到兼容性凭据，以便 SDK 凭据检测正常工作，而代理则使用配置的服务账号对出站请求进行身份验证。

不要将真实的服务账号 JSON 设置为沙盒环境变量。请将它们配置为 workspace_secret 或 opaque 代理值。纯文本 GCP 凭据值会被拒绝。

GCP 认证规则与头注入规则不同：

将 type 设置为 gcp。
将凭据放在 gcp.service_account_json 下。
将 gcp.scopes 设置为非空的 OAuth 作用域列表。
代理会自动匹配 Google API 主机，并使用配置的服务账号对这些请求进行身份验证。
每个沙盒最多配置一个启用的 GCP 认证规则。

SDK 的 gcp_auth 和 gcpAuth 辅助函数会构建相同形状的规则。

curl -X POST "$LANGSMITH_ENDPOINT/v2/sandboxes/boxes" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "gcp-sandbox",
    "wait_for_ready": true,
    "proxy_config": {
      "rules": [
        {
          "name": "gcp",
          "type": "gcp",
          "enabled": true,
          "gcp": {
            "service_account_json": {
              "type": "workspace_secret",
              "value": "{GCP_SERVICE_ACCOUNT_JSON}"
            },
            "scopes": [
              "https://www.googleapis.com/auth/devstorage.read_only"
            ]
          }
        }
      ]
    }
  }'

通过 SDK 配置 GCP 认证

from langsmith.sandbox import (
    SandboxClient,
    gcp_auth,
    proxy_config,
    workspace_secret,
)

client = SandboxClient()

client.create_sandbox(
    name="gcp-sandbox",
    proxy_config=proxy_config(
        rules=[
            gcp_auth(
                service_account_json=workspace_secret("GCP_SERVICE_ACCOUNT_JSON"),
                scopes=["https://www.googleapis.com/auth/devstorage.read_only"],
            )
        ]
    ),
)

import {
  SandboxClient,
  gcpAuth,
  proxyConfig,
  workspaceSecret,
} from "langsmith/sandbox";

const client = new SandboxClient();

await client.createSandbox({
  name: "gcp-sandbox",
  proxyConfig: proxyConfig({
    rules: [
      gcpAuth({
        serviceAccountJson: workspaceSecret("GCP_SERVICE_ACCOUNT_JSON"),
        scopes: ["https://www.googleapis.com/auth/devstorage.read_only"],
      }),
    ],
  }),
});

沙盒就绪后，可在沙盒内正常使用 Google SDK 或 CLI 进行支持的 Google API 请求。SDK 或 CLI 可以发现兼容性凭据，代理则使用配置的服务账号进行真实的 GCP 身份验证，而不会在沙盒内暴露服务账号 JSON。

单个 API 示例

创建一个自动将 OpenAI API 密钥注入出站请求的沙盒：

curl -X POST "$LANGSMITH_ENDPOINT/v2/sandboxes/boxes" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-sandbox",
    "wait_for_ready": true,
    "proxy_config": {
      "rules": [
        {
          "name": "openai-api",
          "match_hosts": ["api.openai.com"],
          "headers": [
            {
              "name": "Authorization",
              "type": "workspace_secret",
              "value": "Bearer {OPENAI_API_KEY}"
            }
          ]
        }
      ]
    }
  }'

现在，沙盒可以在不设置 API 密钥的情况下调用 OpenAI——代理会自动注入它。

多个 API 示例

添加多条规则以同时对多个服务进行身份验证：

curl -X POST "$LANGSMITH_ENDPOINT/v2/sandboxes/boxes" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "multi-api-sandbox",
    "wait_for_ready": true,
    "proxy_config": {
      "rules": [
        {
          "name": "openai-api",
          "match_hosts": ["api.openai.com"],
          "headers": [
            {
              "name": "Authorization",
              "type": "workspace_secret",
              "value": "Bearer {OPENAI_API_KEY}"
            }
          ]
        },
        {
          "name": "anthropic-api",
          "match_hosts": ["api.anthropic.com"],
          "headers": [
            {
              "name": "x-api-key",
              "type": "workspace_secret",
              "value": "{ANTHROPIC_API_KEY}"
            },
            {
              "name": "anthropic-version",
              "type": "plaintext",
              "value": "2023-06-01"
            }
          ]
        },
        {
          "name": "github-api",
          "match_hosts": ["api.github.com"],
          "match_paths": ["/repos/*", "/user"],
          "headers": [
            {
              "name": "Authorization",
              "type": "workspace_secret",
              "value": "Bearer {GITHUB_TOKEN}"
            }
          ]
        }
      ],
      "no_proxy": ["localhost", "127.0.0.1"]
    }
  }'

GitHub 示例

Open SWE 通过在沙盒外部生成一个短期的 GitHub App 安装令牌，然后使用写入专用的 opaque 代理规则修补沙盒，来对 GitHub 访问进行身份验证。这使短期的 GitHub 访问令牌不会出现在沙盒文件系统中，也不会出现在部署环境变量中。配置两条规则：

主机	头
`api.github.com`	`Authorization: Bearer <github-token>`，用于 `gh` 和 REST API 调用
`github.com`, `*.github.com`	`Authorization: Basic <base64("x-access-token:<github-token>")>`，用于 Git over HTTPS 操作，如 clone、fetch 和 push

Python

import base64
import os
from typing import Any

import httpx


def github_proxy_rules(github_token: str) -> list[dict[str, Any]]:
    basic_auth = base64.b64encode(
        f"x-access-token:{github_token}".encode()
    ).decode()

    return [
        {
            "name": "github-api",
            "match_hosts": ["api.github.com"],
            "headers": [
                {
                    "name": "Authorization",
                    "type": "opaque",
                    "value": f"Bearer {github_token}",
                }
            ],
        },
        {
            "name": "github",
            "match_hosts": ["github.com", "*.github.com"],
            "headers": [
                {
                    "name": "Authorization",
                    "type": "opaque",
                    "value": f"Basic {basic_auth}",
                }
            ],
        },
    ]


def configure_github_proxy(sandbox_name: str, github_token: str) -> None:
    endpoint = os.environ.get(
        "LANGSMITH_ENDPOINT", "https://api.smith.langchain.com"
    )
    response = httpx.patch(
        f"{endpoint}/v2/sandboxes/boxes/{sandbox_name}",
        headers={"x-api-key": os.environ["LANGSMITH_API_KEY"]},
        json={"proxy_config": {"rules": github_proxy_rules(github_token)}},
        timeout=30.0,
    )
    response.raise_for_status()

在创建或重新连接到沙盒后调用 configure_github_proxy。GitHub App 安装令牌会过期，因此每当您为新的运行重用沙盒时，请刷新代理配置。在沙盒内部，当 CLI 在发送请求前需要本地凭据时，设置一个非保密的占位符令牌：

GH_TOKEN=dummy gh repo view langchain-ai/langchain
GH_TOKEN=dummy gh pr list --repo langchain-ai/langchain
GH_TOKEN=dummy gh repo clone langchain-ai/langchain

该占位符仅满足 gh CLI 的本地检查。代理会将真实的 Authorization 头注入到出站请求中。

通过 SDK 配置

from langsmith.sandbox import SandboxClient

client = SandboxClient()

client.create_sandbox(
    name="openai-sandbox",
    proxy_config={
        "rules": [
            {
                "name": "openai-api",
                "match_hosts": ["api.openai.com"],
                "headers": [
                    {
                        "name": "Authorization",
                        "type": "workspace_secret",
                        "value": "Bearer {OPENAI_API_KEY}",
                    }
                ],
            }
        ]
    },
)

import { SandboxClient } from "langsmith/sandbox";

const client = new SandboxClient();

await client.createSandbox({
  name: "openai-sandbox",
  proxyConfig: {
    rules: [
      {
        name: "openai-api",
        match_hosts: ["api.openai.com"],
        headers: [
          {
            name: "Authorization",
            type: "workspace_secret",
            value: "Bearer {OPENAI_API_KEY}",
          },
        ],
      },
    ],
  },
});

回调凭据示例

静态 workspace_secret 规则在应用代理配置时从您的工作区拉取凭据，而 opaque 规则允许您的应用程序修补短期凭据，例如 GitHub 令牌示例。对于必须由您自己的服务在代理时解析的凭据，请使用回调。代理会向您提供的 URL 发送 POST 请求，您的端点返回要注入的头，代理缓存结果。回调与 proxy_config 下的规则一起配置：

字段	描述
`match_hosts`	要拦截的主机（与规则相同的语法；支持如 `*.github.com` 的通配符）。
`url`	您的回调端点。必须是代理可访问的 `http://` 或 `https://` URL。
`request_headers`	附加到代理 → 回调请求上的头，例如，您的端点用于验证请求的 HMAC 或共享密钥。仅允许 `plaintext` 和 `opaque` 类型（不允许 `workspace_secret`）。
`ttl_seconds`	解析后的头在重新调用回调前的缓存时间。必须介于 60 到 3600 之间。

静态规则优先。 如果 rules 中的任何规则匹配该主机，则会跳过该主机的回调。在规则中，首次匹配优先；如果多个回调匹配，规则之间也适用此规则。

回调契约

每当代理需要解析缓存未命中（cache miss）的匹配主机的凭据时，会发出以下请求：

POST <callback.url>
Content-Type: application/json
<请求头 来自您的配置，逐字附加>

{"host": "api.example.com", "port": 443}

您的端点必须以 2xx 响应，并包含 JSON 主体：

{
  "headers": {
    "Authorization": "Bearer <token>",
    "X-Org-Id": "..."
  }
}

代理将响应中的每个头注入沙盒的出站请求，并将响应缓存 ttl_seconds 秒。任何非 2xx 响应、传输错误或格式错误的 JSON 都会导致失败关闭（fail closed）：沙盒的请求会被拒绝，并返回 502 callback resolution failed（不注入头，不缓存响应）。

示例

当您的 OAuth 令牌由您自己的服务按需生成时，请使用回调：

curl -X POST "$LANGSMITH_ENDPOINT/v2/sandboxes/boxes" \
  -H "x-api-key: $LANGSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "<snapshot-uuid>",
    "name": "callback-sandbox",
    "wait_for_ready": true,
    "proxy_config": {
      "callbacks": [
        {
          "match_hosts": ["api.github.com", "*.githubusercontent.com"],
          "url": "https://auth.your-app.example.com/sandbox-credentials",
          "request_headers": [
            {
              "name": "X-Integrator-Secret",
              "type": "opaque",
              "value": "<shared-secret-your-endpoint-verifies>"
            }
          ],
          "ttl_seconds": 300
        }
      ]
    }
  }'

通过 SDK 配置

from langsmith.sandbox import SandboxClient

client = SandboxClient()

client.create_sandbox(
    name="callback-sandbox",
    proxy_config={
        "callbacks": [
            {
                "match_hosts": ["api.github.com", "*.githubusercontent.com"],
                "url": "https://auth.your-app.example.com/sandbox-credentials",
                "request_headers": [
                    {
                        "name": "X-Integrator-Secret",
                        "type": "opaque",
                        "value": "<shared-secret-your-endpoint-verifies>",
                    }
                ],
                "ttl_seconds": 300,
            }
        ]
    },
)

import { SandboxClient } from "langsmith/sandbox";

const client = new SandboxClient();

await client.createSandbox({
  name: "callback-sandbox",
  proxyConfig: {
    callbacks: [
      {
        match_hosts: ["api.github.com", "*.githubusercontent.com"],
        url: "https://auth.your-app.example.com/sandbox-credentials",
        request_headers: [
          {
            name: "X-Integrator-Secret",
            type: "opaque",
            value: "<shared-secret-your-endpoint-verifies>",
          },
        ],
        ttl_seconds: 300,
      },
    ],
  },
});

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​出口流量与网络访问控制

​默认出口策略

​允许列表和拒绝列表

​模式语法

​连接数据库（原始 TCP）

​通过 SDK 配置

​配置认证代理规则

​头类型

​认证 AWS 请求

​通过 SDK 配置 AWS 认证

​认证 GCP 请求

​通过 SDK 配置 GCP 认证

​单个 API 示例

​多个 API 示例

​GitHub 示例

​通过 SDK 配置

​回调凭据示例

​回调契约

​示例

​通过 SDK 配置

出口流量与网络访问控制

默认出口策略

允许列表和拒绝列表

模式语法

连接数据库（原始 TCP）

通过 SDK 配置

配置认证代理规则

头类型

认证 AWS 请求

通过 SDK 配置 AWS 认证

认证 GCP 请求

通过 SDK 配置 GCP 认证

单个 API 示例

多个 API 示例

GitHub 示例

通过 SDK 配置

回调凭据示例

回调契约

示例

通过 SDK 配置