adding-env-variables

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Adding Environment Variables Guide

环境变量添加指南

Comprehensive guidance for adding new environment variables to the Inkeep Agent Framework. This ensures consistency, documentation, and type safety across all packages.

这是一份为Inkeep Agent Framework添加新环境变量的全面指南，可确保所有包之间的一致性、文档完整性和类型安全性。

CI Enforcement

CI 强制校验

Environment variable descriptions are enforced by CI. The

check:env-descriptions

script runs in CI and will fail if any variables in

env.ts

files are missing

.describe()

calls.

Run locally to check:

bash

pnpm check:env-descriptions

环境变量描述由CI强制校验。

check:env-descriptions

脚本会在CI中运行，如果

env.ts

文件中的任何变量缺少

.describe()

调用，CI将执行失败。

可在本地运行以下命令进行检查：

bash

pnpm check:env-descriptions

Environment Architecture

环境架构

The framework uses environment variables defined in multiple

env.ts

files:

Package	File	Purpose
agents-api	`agents-api/src/env.ts`	Main API server configuration
agents-core	`packages/agents-core/src/env.ts`	Shared core configuration
agents-cli	`agents-cli/src/env.ts`	CLI tool configuration

Note: The following files are auto-generated and should NOT be edited:

```
packages/agents-mcp/src/lib/env.ts
```
(Generated by Speakeasy)

该框架使用在多个

env.ts

文件中定义的环境变量：

包	文件	用途
agents-api	`agents-api/src/env.ts`	主API服务器配置
agents-core	`packages/agents-core/src/env.ts`	共享核心配置
agents-cli	`agents-cli/src/env.ts`	CLI工具配置

注意： 以下文件为自动生成，请勿编辑：

```
packages/agents-mcp/src/lib/env.ts
```
(由Speakeasy生成)

Required Steps for Adding Environment Variables

添加环境变量的必要步骤

Step 1: Add to

.env.example

步骤1：添加到

.env.example

Location:

.env.example

(root of repository)

Add the variable with a descriptive comment:

bash

undefined

位置：仓库根目录下的

.env.example

添加变量并附上描述性注释：

bash

undefined

============ SECTION NAME ============

============ 章节名称 ============

Description of what this variable does

该变量的用途说明

Additional context if needed (e.g., where to get API keys)

必要的额外上下文（例如，获取API密钥的途径）

MY_NEW_VARIABLE=default-value-or-empty


**Example:**

```bash

MY_NEW_VARIABLE=默认值或留空


**示例：**

```bash

============ AI PROVIDERS ============

============ AI 服务商 ============

Required for agent execution

代理执行所需

Get your API keys from:

从以下地址获取API密钥：

Anthropic: https://console.anthropic.com/

OpenAI: https://platform.openai.com/

ANTHROPIC_API_KEY= OPENAI_API_KEY=

undefined

ANTHROPIC_API_KEY= OPENAI_API_KEY=

undefined

Step 2: Add to Relevant

env.ts

File(s)

步骤2：添加到对应的

env.ts

文件

Add the variable to the Zod schema with a

.describe()

call that matches the

.env.example

comment:

typescript

const envSchema = z.object({
  // ... existing variables ...

  MY_NEW_VARIABLE: z
    .string()
    .optional()
    .describe('Description of what this variable does'),
});

将变量添加到Zod模式中，并调用

.describe()

，其内容需与

.env.example

中的注释一致：

typescript

const envSchema = z.object({
  // ... 现有变量 ...

  MY_NEW_VARIABLE: z
    .string()
    .optional()
    .describe('该变量的用途说明'),
});

Step 3: Description Requirements

步骤3：描述要求

Every environment variable MUST have a
.describe()
call with a clear, concise description that:

Explains what the variable is used for
Matches the comment in
```
.env.example
```
Includes helpful context (e.g., where to get API keys, default behavior)

Examples of good descriptions:

typescript

// AI Provider keys
ANTHROPIC_API_KEY: z
  .string()
  .describe('Anthropic API key for Claude models (required for agent execution). Get from https://console.anthropic.com/'),

// Database configuration
INKEEP_AGENTS_MANAGE_DATABASE_URL: z
  .string()
  .describe('PostgreSQL connection URL for the management database (Doltgres with Git version control)'),

// Authentication
BETTER_AUTH_SECRET: z
  .string()
  .optional()
  .describe('Secret key for Better Auth session encryption (change in production)'),

// Feature flags
LANGFUSE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable Langfuse LLM observability (set to "true" to enable)'),

每个环境变量必须调用
.describe()
，且描述需清晰、简洁，满足以下要求：

说明变量的用途
与
```
.env.example
```
中的注释保持一致
包含有用的上下文（例如，获取API密钥的途径、默认行为）

优秀描述示例：

typescript

// AI服务商密钥
ANTHROPIC_API_KEY: z
  .string()
  .describe('用于Claude模型的Anthropic API密钥（代理执行所需）。从https://console.anthropic.com/获取'),

// 数据库配置
INKEEP_AGENTS_MANAGE_DATABASE_URL: z
  .string()
  .describe('用于管理数据库的PostgreSQL连接URL（带Git版本控制的Doltgres）'),

// 认证
BETTER_AUTH_SECRET: z
  .string()
  .optional()
  .describe('用于Better Auth会话加密的密钥（生产环境需修改）'),

// 功能开关
LANGFUSE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('启用Langfuse LLM可观测性（设置为"true"以启用）'),

Zod Schema Patterns

Zod 模式示例

Required Variables

必填变量

typescript

MY_REQUIRED_VAR: z
  .string()
  .describe('This variable is required for the application to function'),

typescript

MY_REQUIRED_VAR: z
  .string()
  .describe('该变量是应用正常运行的必填项'),

Optional Variables

可选变量

typescript

MY_OPTIONAL_VAR: z
  .string()
  .optional()
  .describe('Optional configuration for feature X'),

typescript

MY_OPTIONAL_VAR: z
  .string()
  .optional()
  .describe('功能X的可选配置'),

Variables with Defaults

带默认值的变量

typescript

MY_VAR_WITH_DEFAULT: z
  .string()
  .optional()
  .default('default-value')
  .describe('Configuration with a sensible default'),

typescript

MY_VAR_WITH_DEFAULT: z
  .string()
  .optional()
  .default('default-value')
  .describe('带有合理默认值的配置项'),

Enum Variables

枚举变量

typescript

LOG_LEVEL: z
  .enum(['trace', 'debug', 'info', 'warn', 'error'])
  .default('info')
  .describe('Logging verbosity level'),

typescript

LOG_LEVEL: z
  .enum(['trace', 'debug', 'info', 'warn', 'error'])
  .default('info')
  .describe('日志详细级别'),

Numeric Variables

数值型变量

typescript

POOL_SIZE: z
  .coerce.number()
  .optional()
  .default(10)
  .describe('Maximum number of connections in the pool'),

typescript

POOL_SIZE: z
  .coerce.number()
  .optional()
  .default(10)
  .describe('连接池的最大连接数'),

Boolean Variables (as strings)

布尔型变量（以字符串形式存储）

typescript

FEATURE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable feature X (set to "true" to enable)'),

typescript

FEATURE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('启用功能X（设置为"true"以启用）'),

Variables with Validation

带校验规则的变量

typescript

JWT_SECRET: z
  .string()
  .min(32, 'JWT_SECRET must be at least 32 characters')
  .optional()
  .describe('Secret key for signing JWT tokens (minimum 32 characters)'),

ADMIN_EMAIL: z
  .string()
  .optional()
  .refine((val) => !val || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val), {
    message: 'Invalid email address',
  })
  .describe('Admin email address for notifications'),

typescript

JWT_SECRET: z
  .string()
  .min(32, 'JWT_SECRET必须至少32个字符')
  .optional()
  .describe('用于签名JWT令牌的密钥（最少32个字符）'),

ADMIN_EMAIL: z
  .string()
  .optional()
  .refine((val) => !val || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val), {
    message: '无效的邮箱地址',
  })
  .describe('用于接收通知的管理员邮箱地址'),

Category Organization

分类组织

Group related variables with comments in both

.env.example

and

env.ts

在

.env.example

和

env.ts

中，使用注释将相关变量分组：

.env.example

在

.env.example

中：

bash

undefined

bash

undefined

============ DATABASE ============

============ 数据库 ============

INKEEP_AGENTS_MANAGE_DATABASE_URL=... INKEEP_AGENTS_RUN_DATABASE_URL=...

============ AI PROVIDERS ============

============ AI 服务商 ============

ANTHROPIC_API_KEY= OPENAI_API_KEY=

undefined

ANTHROPIC_API_KEY= OPENAI_API_KEY=

undefined

env.ts

在

env.ts

中：

typescript

const envSchema = z.object({
  // Database
  INKEEP_AGENTS_MANAGE_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the management database'),
  INKEEP_AGENTS_RUN_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the runtime database'),

  // AI Providers
  ANTHROPIC_API_KEY: z
    .string()
    .describe('Anthropic API key for Claude models'),
  OPENAI_API_KEY: z
    .string()
    .optional()
    .describe('OpenAI API key for GPT models'),
});

typescript

const envSchema = z.object({
  // 数据库
  INKEEP_AGENTS_MANAGE_DATABASE_URL: z
    .string()
    .describe('用于管理数据库的PostgreSQL连接URL'),
  INKEEP_AGENTS_RUN_DATABASE_URL: z
    .string()
    .describe('用于运行时数据库的PostgreSQL连接URL'),

  // AI服务商
  ANTHROPIC_API_KEY: z
    .string()
    .describe('用于Claude模型的Anthropic API密钥'),
  OPENAI_API_KEY: z
    .string()
    .optional()
    .describe('用于GPT模型的OpenAI API密钥'),
});

Which

env.ts

File to Use?

选择哪个

env.ts

文件？

Choose the appropriate file based on where the variable is used:

Use Case	File
API server configuration	`agents-api/src/env.ts`
Shared across packages	`packages/agents-core/src/env.ts`
CLI-specific	`agents-cli/src/env.ts`
Multiple packages	Add to `agents-core` and import where needed

根据变量的使用场景选择合适的文件：

使用场景	文件
API服务器配置	`agents-api/src/env.ts`
多包共享	`packages/agents-core/src/env.ts`
CLI专属	`agents-cli/src/env.ts`
多包使用	添加到 `agents-core` 并在需要的地方导入

Checklist for Adding Environment Variables

添加环境变量检查清单

Before completing any environment variable addition, verify:

Variable added to
```
.env.example
```
with descriptive comment
Variable added to relevant
```
env.ts
```
file(s)
```
.describe()
```
call added with clear description
Description matches
```
.env.example
```
comment
Appropriate Zod type used (string, number, enum, etc.)
```
optional()
```
added if variable is not required
```
default()
```
added if there's a sensible default
Validation added if needed (min, max, refine, etc.)
Variable grouped with related variables (using comments)
```
pnpm check:env-descriptions
```
passes locally

完成环境变量添加前，请确认以下事项：

变量已添加到
```
.env.example
```
并附上描述性注释
变量已添加到对应的
```
env.ts
```
文件
已添加
```
.describe()
```
调用并包含清晰的描述
描述与
```
.env.example
```
中的注释一致
使用了合适的Zod类型（字符串、数字、枚举等）
若变量为可选，已添加
```
optional()
```
若有合理默认值，已添加
```
default()
```
必要时已添加校验规则（最小长度、最大长度、refine等）
变量已通过注释与相关变量分组
本地运行
```
pnpm check:env-descriptions
```
已通过

Common Mistakes to Avoid

需避免的常见错误

Missing
.describe()
call - Every variable needs a description (CI will fail!)
Inconsistent descriptions - Keep
```
.env.example
```
and
```
.describe()
```
in sync
Wrong file - Add to the package that actually uses the variable
Missing validation - Add constraints for sensitive values (min length for secrets, email validation, etc.)
Editing auto-generated files - Never edit
```
agents-mcp
```
env files

缺少
.describe()
调用 - 每个变量都需要描述（CI会执行失败！）
描述不一致 - 保持
```
.env.example
```
和
```
.describe()
```
的内容同步
选错文件 - 将变量添加到实际使用它的包中
缺少校验规则 - 对敏感值添加约束（密钥的最小长度、邮箱校验等）
编辑自动生成的文件 - 切勿编辑
```
agents-mcp
```
相关的环境文件

adding-env-variables

Original

Translation

Adding Environment Variables Guide

环境变量添加指南

CI Enforcement

CI 强制校验

Environment Architecture

环境架构

Required Steps for Adding Environment Variables

添加环境变量的必要步骤

Step 1: Add to .env.example

步骤1：添加到.env.example

============ SECTION NAME ============

============ 章节名称 ============

Description of what this variable does

该变量的用途说明

Additional context if needed (e.g., where to get API keys)

必要的额外上下文（例如，获取API密钥的途径）

============ AI PROVIDERS ============

============ AI 服务商 ============

Required for agent execution

代理执行所需

Get your API keys from:

从以下地址获取API密钥：

Anthropic: https://console.anthropic.com/

Anthropic: https://console.anthropic.com/

OpenAI: https://platform.openai.com/

OpenAI: https://platform.openai.com/

Step 2: Add to Relevant env.ts File(s)

步骤2：添加到对应的env.ts文件

Step 3: Description Requirements

步骤3：描述要求

Zod Schema Patterns

Zod 模式示例

Required Variables

必填变量

Optional Variables

可选变量

Variables with Defaults

带默认值的变量

Enum Variables

枚举变量

Numeric Variables

数值型变量

Boolean Variables (as strings)

布尔型变量（以字符串形式存储）

Variables with Validation

带校验规则的变量

Category Organization

分类组织

In .env.example:

在.env.example中：

============ DATABASE ============

============ 数据库 ============

============ AI PROVIDERS ============

============ AI 服务商 ============

In env.ts:

在env.ts中：

Which env.ts File to Use?

选择哪个env.ts文件？

Checklist for Adding Environment Variables

添加环境变量检查清单

Common Mistakes to Avoid

需避免的常见错误

Step 1: Add to
`.env.example`

步骤1：添加到
`.env.example`

Step 2: Add to Relevant
`env.ts`
File(s)

步骤2：添加到对应的
`env.ts`
文件

In
`.env.example`
:

在
`.env.example`
中：

In
`env.ts`
:

在
`env.ts`
中：

Which
`env.ts`
File to Use?

选择哪个
`env.ts`
文件？