> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 环境变量

环境变量可为工具 URL、密钥、标头和身份验证连接定义每个环境的值。单个智能体和工具配置可在所有环境中使用——URL、API 密钥和身份验证会根据对话时指定的环境动态解析。

## 概览

如果没有环境变量，要将智能体部署到多个环境（开发、预发布、生产），就需要为每个环境复制智能体和工具，然后手动保持其配置同步。这会导致：

* 环境之间出现**配置偏移**
* 重复的智能体 ID 导致**分析数据分散**
* 从预发布环境迁移到生产环境时出现**发布阻碍**

环境变量通过引入可复用、工作区范围的资源来解决这些问题，该资源会为每个环境存储不同值。工具和 MCP 服务器使用模板语法引用这些变量，并会在运行时根据对话环境解析正确的值。

![环境变量概览](/docs/_fern-img/75bbfad6349ff43d078f62e75f7d3549858897158e55ada3dcdbf261a963b055.webp)

## 核心概念

### 环境变量

环境变量是一个工作区范围的资源，包含标签和一组按环境区分的值。共有 3 种类型：

| 类型         | 描述             | 示例使用场景                        |
| ---------- | -------------- | ----------------------------- |
| **字符串**    | 因环境而异的纯文本值     | 基础 URL、主机名、配置值                |
| **密钥**     | 按环境解析的工作区密钥引用  | API 密钥、Bearer 令牌、Webhook 签名密钥 |
| **身份验证连接** | 按环境解析的身份验证连接引用 | OAuth2 凭据、JWT 配置              |

每个环境变量都必须为默认 `production` 环境设置值。其他环境（例如 `staging`、`development`）为可选项。

### 模板语法

可在 URL 字段中使用 `{{system__env_<label>}}` 语法引用环境变量：

```
https://{{system__env_api_host}}.example.com/v1/text-to-speech
```

对于值为 `api`（生产环境）和 `staging.api`（预发布环境）的环境变量 `api_host`，会解析为：

* 在 `production` 中：`https://api.example.com/v1/text-to-speech`
* 在 `staging` 中：`https://staging.api.example.com/v1/text-to-speech`

此语法与[动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)一致，适用于 Webhook 工具和 MCP 服务器连接的 URL 字段。

> **Note**
>
> 环境变量同样支持用于**通话前 Webhook** URL 和标头（对话发起客户端数据 Webhook），以及在**开发者 > Webhook**下配置的**通话后 Webhook** URL。模板会使用对话环境解析，因此同一 Webhook 配置可按环境指向不同端点。对于通话前 Webhook，可预先在电话号码上设置环境，也可在 Webhook 响应中动态返回环境（参见下方[电话](#telephony-twilio-and-sip-trunk)）。

> **Note**
>
> URL 必须以 `https://` 开头，之后才能使用任何环境变量引用。例如，`https://   {{ system__env_api_host }}.example.com/v1/data` 有效，但 `{{ system__env_api_host }}/v1/data`
> 无效。这是验证和安全要求——环境变量值不能控制协议。

### 解析和回退

当对话在特定环境中运行时，系统会按以下方式解析环境变量：

1. 查找请求环境（例如 `staging`）的值
2. 如果该环境没有值，**回退到 `production` 值**
3. 如果无法解析变量，工具调用会因配置错误而失败

这种回退行为意味着只需为与生产环境不同的环境定义值。

## 创建环境变量

> **Note**
>
> 目前无法通过 ElevenLabs CLI 管理环境变量——请使用控制台或 SDK。

#### 通过控制台创建

在 ElevenLabs 控制台中前往**开发者 > 环境变量**。

#### 创建环境

定义与部署阶段对应的环境（例如 `eu`、`india`、`staging`）。默认始终提供 `production` 环境。

#### 创建变量

点击**添加变量**，然后选择变量类型：

* **字符串**：输入标签，并为每个环境设置值
* **密钥**：为每个环境选择现有工作区密钥
* **身份验证连接**：为每个环境选择现有身份验证连接

![创建变量](/docs/_fern-img/8ab18d57956167aaa152e10b4d2890b208c8ba826ef0cbbf9082c8e1602f5246.webp)

#### 通过 API 创建

#### 字符串

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="api_host",
    type="string",
    values={
        "production": "api",
        "staging": "staging.api",
        "development": "dev.api",
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "api_host",
  type: "string",
  values: {
    production: "api",
    staging: "staging.api",
    development: "dev.api",
  },
});
```

#### 密钥

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_api_key",
    type="secret",
    values={
        "production": {"secret_id": "your-production-secret-id"},
        "staging": {"secret_id": "your-staging-secret-id"},
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_api_key",
  type: "secret",
  values: {
    production: { secretId: "your-production-secret-id" },
    staging: { secretId: "your-staging-secret-id" },
  },
});
```

#### 身份验证连接

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.environment_variables.create(
    label="my_oauth_connection",
    type="auth_connection",
    values={
        "production": {"auth_connection_id": "your-production-auth-connection-id"},
        "staging": {"auth_connection_id": "your-staging-auth-connection-id"},
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.environmentVariables.create({
  label: "my_oauth_connection",
  type: "auth_connection",
  values: {
    production: { authConnectionId: "your-production-auth-connection-id" },
    staging: { authConnectionId: "your-staging-auth-connection-id" },
  },
});
```

## 使用环境变量

### 在 webhook 工具 URL 中使用

在 [webhook 工具](/docs/zh/eleven-agents/customization/tools/webhook-tools)的 URL 字段中使用模板语法，让基础 URL 按环境解析。

![工具 URL 中的环境变量](/docs/_fern-img/8a9d4a7fbd589565c57f52aa82200c28fe7fcfcc80ff9a3ec41a99ca315a9f50.webp)

例如，配置为以下内容的工具 URL：

```
https://{{system__env_api_host}}.example.com/v1/weather?lat={latitude}&lon={longitude}
```

在生产环境中会解析为 `https://api.example.com/v1/weather?lat=40.7&lon=-74.0`，在预发布环境中则解析为 `https://staging.api.example.com/v1/weather?lat=40.7&lon=-74.0`。

可在单个 URL 中组合多个环境变量和字面量片段：

```
https://{{system__env_api_host}}.example.com/{{system__env_api_version}}/weather
```

#### API 示例

**`Python`**

```python title="Python"

from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key="your-api-key")

agent = client.conversational_ai.agents.create(
    conversation_config={
        "agent": {
            "first_message": "Hello! How can I help?",
            "prompt": {"prompt": "You are a helpful assistant."},
        },
        "tools": [
            {
                "type": "webhook",
                "name": "get_data",
                "description": "Fetches data from the API",
                "api_schema": {
                    "url": "https://{{system__env_api_host}}.example.com/v1/data",
                    "method": "GET",
                },
            }
        ],
    },
)
```

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const agent = await client.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hello! How can I help?",
      prompt: { prompt: "You are a helpful assistant." },
    },
    tools: [
      {
        type: "webhook",
        name: "get_data",
        description: "Fetches data from the API",
        apiSchema: {
          url: "https://{{system__env_api_host}}.example.com/v1/data",
          method: "GET",
        },
      },
    ],
  },
});
```

### 在 webhook 工具请求头中使用

可在请求头中使用密钥环境变量。不要硬编码密钥 ID，而是引用环境变量，以便不同环境使用不同密钥。在控制台配置工具请求头时，选择环境变量而非静态密钥。运行时，请求头值会解析为当前环境中存储的密钥。

#### API 示例

在 `request_headers` 字段中传入环境变量引用：

```json
{
  "api_schema": {
    "url": "https://{{system__env_api_host}}.example.com/v1/data",
    "method": "GET",
    "request_headers": {
      "X-Api-Key": { "env_var_label": "my_api_key" }
    }
  }
}
```

### 在 webhook 工具认证连接中使用

认证连接（OAuth2、JWT、Basic Auth）也可按环境解析。当预发布和生产环境使用不同的 OAuth 客户端或令牌端点时，这非常有用。

![环境变量认证连接](/docs/_fern-img/41115e31cac8c55360cb4f5783a4d03cf63ea51a6f5baa2812993d70d7c4a4d5.webp)

在工具配置中，选择类型为 `auth_connection` 的环境变量，而不是直接选择认证连接。运行时会解析当前环境对应的正确认证连接。

#### API 示例

在 `auth_connection` 字段中引用环境变量：

```json
{
  "api_schema": {
    "url": "https://{{system__env_api_host}}.example.com/v1/data",
    "method": "GET",
    "auth_connection": { "env_var_label": "my_oauth_connection" }
  }
}
```

### 在 MCP 服务器连接中使用

环境变量在 [MCP 服务器](/docs/zh/eleven-agents/customization/tools/mcp)连接中的使用方式与 webhook 工具相同。可用于：

* **服务器 URL**：将 MCP 服务器 URL 设为模板，按环境指向不同服务器
* **请求头**：为认证请求头使用密钥环境变量
* **认证连接**：为基于 OAuth 的 MCP 服务器使用认证连接环境变量

例如，配置为以下内容的 MCP 服务器 URL：

```
https://{{system__env_mcp_host}}.example.com/mcp
```

会根据环境解析为不同的 MCP 服务器端点。

### 在自定义 LLM 配置中使用

使用[自定义 LLM](/docs/zh/eleven-agents/customization/llm/custom-llm)时，环境变量可为 API 密钥和请求头设置模板。这样可在不同环境中使用不同的模型端点和凭据。

自定义 LLM URL 字段支持相同的 `{{system__env_<label>}}` 模板语法。`api_key` 字段接受环境变量引用，以便不同环境使用不同 API 密钥。

#### API 示例

```json
{
  "conversation_config": {
    "agent": {
      "prompt": { "prompt": "You are a helpful assistant." },
      "llm": {
        "custom_llm": {
          "url": "https://{{system__env_llm_host}}.example.com/v1/chat/completions",
          "model_id": "my-model",
          "api_key": { "env_var_label": "llm_api_key" }
        }
      }
    }
  }
}
```

## 指定环境

环境在对话开始时设置，并在整个对话期间保持不变。未指定环境时，默认为 `production`。

在控制台中测试时，可在智能体预览的下拉菜单中选择环境：

![智能体预览环境
选择器](/docs/_fern-img/052880e903ac2dc3539a0ed84feef5a3d31cd28c9b1345705c9003796d382803.webp)

### WebSocket

连接对话 WebSocket 时传入 `environment` 查询参数：

```
wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<agent_id>&environment=staging
```

### WebRTC（签名 URL / 令牌）

使用 WebRTC 时，请在请求对话令牌时传入 `environment` 参数：

**`Python`**

```python title="Python"
from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key="your-api-key")

token = client.conversational_ai.conversation.get_token(
agent_id="your-agent-id",
environment="staging",
)

```

**`JavaScript`**

```javascript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

const token = await client.conversationalAi.conversation.getToken({
    agentId: "your-agent-id",
    environment: "staging",
});
```

**`cURL`**

```bash title="cURL"
curl "https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=<agent_id>&environment=staging" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"
```

### 电话（Twilio 和 SIP 中继）

电话号码可固定到特定环境和特定[智能体分支](/docs/zh/eleven-agents/operate/versioning)，便于将测试电话号码路由到智能体的开发分支，而该分支的工具会针对开发 API 执行。

![电话号码环境和分支
选择器](/docs/_fern-img/ba83735f5cad2006555eb73a12a520c7c86fa3d576d8f69f481a8c75d315cf1d.webp)

对于呼入电话，环境会按以下顺序解析：

1. 如果服务器为每次通话动态提供，则使用[对话发起 webhook](/docs/zh/eleven-agents/customization/personalization#conversation-initiation-webhooks)返回的 `environment` 值
2. 存储在**电话号码**上的环境
3. 默认使用 `production`

`branch_id` 也遵循相同优先级。随后，通话前 webhook URL 和请求头，以及通话后 webhook URL，会使用所选环境解析 `{{system__env_*}}` 模板。

将电话号码固定到环境和分支（需要 `elevenlabs` Python SDK ≥ 2.47.0 或 `@elevenlabs/elevenlabs-js` ≥ 2.47.0）：

**`Python`**

```python title="Python"
import os
from dotenv import load_dotenv
from elevenlabs import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

elevenlabs.conversational_ai.phone_numbers.update(
    phone_number_id="phnum_8901k4t9z5defmb8vh3e9361y7nj",
    environment="staging",
    branch_id="agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
)
```

**`JavaScript`**

```typescript title="JavaScript"
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.phoneNumbers.update("phnum_8901k4t9z5defmb8vh3e9361y7nj", {
  environment: "staging",
  branchId: "agtbrch_8901k4t9z5defmb8vh3e9361y7nj",
});
```

**`cURL`**

```bash title="cURL"
curl -X PATCH "https://api.elevenlabs.io/v1/convai/phone-numbers/phnum_8901k4t9z5defmb8vh3e9361y7nj" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "branch_id": "agtbrch_8901k4t9z5defmb8vh3e9361y7nj"
  }'
```

对于呼出电话，通过 Twilio 或 SIP 中继呼出端点发起通话时，传入 `environment` 字段。

### React SDK

在 `useConversation` hook 中或启动会话时传入 `environment` 选项：

```tsx
import { useConversation } from "@11labs/react";

function Agent() {
  const conversation = useConversation();

  const connect = async () => {
    await conversation.startSession({
      agentId: "your-agent-id",
      environment: "staging",
    });
  };

  return <button onClick={connect}>Start conversation</button>;
}
```

## 示例：多环境智能体

本示例展示了完整设置：单个智能体可在开发、预发布和生产环境中使用不同的 API 后端与凭据。

#### 创建环境变量

在控制台或通过 API 创建 3 个环境变量：

| 标签            | 类型   | 开发              | 预发布                 | 生产               |
| ------------- | ---- | --------------- | ------------------- | ---------------- |
| `api_host`    | 字符串  | `dev.api`       | `staging.api`       | `api`            |
| `api_key`     | 密钥   | `dev-secret-id` | `staging-secret-id` | `prod-secret-id` |
| `oauth_creds` | 认证连接 | `dev-oauth-id`  | `staging-oauth-id`  | `prod-oauth-id`  |

#### 使用环境变量引用配置工具

使用模板语法设置 webhook 工具：

* **URL**：`https://{{system__env_api_host}}.example.com/v1/orders`
* **请求头**：为 `X-Api-Key` 请求头引用 `api_key` 环境变量
* **认证**：为 OAuth 认证引用 `oauth_creds` 环境变量

#### 在对话时指定环境

启动对话时，传入目标环境：

**`开发`**

```python title="开发"
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="development",
)
```

**`预发布`**

```python title="预发布"
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
    environment="staging",
)
```

**`生产（默认）`**

```python title="生产（默认）"
# No environment parameter needed — defaults to production
conversation = client.conversational_ai.conversation.get_signed_url(
    agent_id="your-agent-id",
)
```

#### 按环境筛选

每次对话都会记录环境。可按环境筛选分析仪表板和对话历史记录，以分别查看各部署阶段的指标。

![按环境筛选分析数据](/docs/_fern-img/640f45e330a6f58648bb79fb588b580bb1d938e20f46c453b6d0c0efdac04054.webp)

![按环境筛选对话历史记录](/docs/_fern-img/de6cdcdad31761a4e94928ea125503a555635eaf579521096b5f38d5ef931cd0.webp)

### 命名限制

* **标签**：仅限字母数字字符和下划线（例如 `base_url`、`api_key_v2`）
* **环境名称**：必须以小写字母开头，且只能包含小写字母、数字、下划线和连字符，最长 64 个字符（例如 `production`、`staging`、`dev-us-east`）
* 每个环境变量都必须有 `production` 值

## 后续步骤

#### [Webhook 工具](/docs/zh/eleven-agents/customization/tools/webhook-tools)

使用感知环境的 URL 和认证配置 webhook 工具

#### [MCP 服务器](/docs/zh/eleven-agents/customization/tools/mcp)

使用按环境配置连接 MCP 服务器

#### [自定义 LLM](/docs/zh/eleven-agents/customization/llm/custom-llm)

在不同环境中使用不同模型端点

#### [版本控制](/docs/zh/eleven-agents/operate/versioning)

将环境变量与分支和流量拆分结合使用