> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.
# 环境变量
> Shannon 配置的完整环境变量参考
## 概述
Shannon 使用环境变量在所有服务中进行配置。本页面记录了所有 100+ 个配置选项,包括类型、默认值和影响。
## 快速参考
| 类别 | 变量数 | 服务 |
| ---------------------------- | --- | ------------------------- |
| [核心运行时](#核心运行时) | 3 | 所有 |
| [LLM 提供商密钥](#llm-提供商-api-密钥) | 11 | LLM Service |
| [网页搜索](#网页搜索提供商) | 6 | LLM Service |
| [数据存储](#数据存储) | 17 | 所有 |
| [服务端点](#服务端点) | 8 | 所有 |
| [模型路由](#模型路由和预算) | 13 | Orchestrator, LLM Service |
| [缓存和速率限制](#缓存和速率限制) | 8 | 所有 |
| [工具执行](#工具执行和工作流) | 11 | Orchestrator, Agent Core |
| [安全](#审批和安全) | 6 | Gateway, Orchestrator |
| [可观测性](#可观测性和遥测) | 5 | 所有 |
| [WASI 沙箱](#python-wasi-沙箱) | 4 | Agent Core, LLM Service |
| [集成](#openapi-和-mcp) | 13 | LLM Service |
| [高级](#高级-orchestrator-控制) | 20+ | Orchestrator |
**总计**: 100+ 个配置变量
## 配置文件
将 `.env.example` 复制到 `.env` 并自定义:
```bash theme={null}
cp .env.example .env
nano .env
```
更改后重启服务:
```bash theme={null}
docker compose restart
```
## 核心运行时
### ENVIRONMENT
**类型**: String
**默认值**: `dev`
**有效值**: `dev`, `staging`, `prod`
**服务**: 所有
**热重载**: 否 (需要重启)
控制日志详细程度和策略执行。
```bash theme={null}
ENVIRONMENT=prod
```
**影响**:
* `dev`: 详细日志, 宽松策略
* `staging`: 适度日志, 标准策略
* `prod`: 最少日志, 严格策略
### DEBUG
**类型**: Boolean
**默认值**: `false`
**有效值**: `true`, `false`
**服务**: 所有
**热重载**: 否
在所有服务中启用调试日志。
```bash theme={null}
DEBUG=true
```
**影响**:
* `true`: 调试级别日志, 堆栈跟踪
* `false`: 仅信息级别日志
### SERVICE\_NAME
**类型**: String
**默认值**: `shannon-llm-service`
**服务**: LLM Service
**热重载**: 否
用于日志记录和遥测的服务标识符。
```bash theme={null}
SERVICE_NAME=shannon-llm-service
```
## LLM 提供商 API 密钥
### OPENAI\_API\_KEY
**类型**: String
**必需**: 至少一个提供商密钥
**服务**: LLM Service
**热重载**: 是
用于 GPT 模型的 OpenAI API 密钥。
```bash theme={null}
OPENAI_API_KEY=sk-...
```
**启用的模型**: GPT-5, GPT-5-mini, GPT-5-nano
语义记忆功能（文本嵌入）必需。如果未设置此密钥，向量搜索和 agent 记忆功能将被禁用。
### ANTHROPIC\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
用于 Claude 模型的 Anthropic API 密钥。
```bash theme={null}
ANTHROPIC_API_KEY=sk-ant-...
```
**启用的模型**: Claude 4.5 Sonnet, Claude 4.1 Opus, Claude 4.5 Haiku
### GOOGLE\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
用于 Gemini 模型的 Google AI API 密钥。
```bash theme={null}
GOOGLE_API_KEY=...
```
**启用的模型**: Gemini Pro, Gemini Flash
### GROQ\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
用于快速推理的 Groq API 密钥。
```bash theme={null}
GROQ_API_KEY=...
```
**启用的模型**: Llama 3, Mixtral
### XAI\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
用于 Grok 模型的 xAI API 密钥。
```bash theme={null}
XAI_API_KEY=...
```
### DEEPSEEK\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
DeepSeek API 密钥。
```bash theme={null}
DEEPSEEK_API_KEY=...
```
### QWEN\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
用于阿里云模型的 Qwen API 密钥。
```bash theme={null}
QWEN_API_KEY=...
```
### MISTRAL\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
Mistral API 密钥。
```bash theme={null}
MISTRAL_API_KEY=...
```
### AWS\_ACCESS\_KEY\_ID / AWS\_SECRET\_ACCESS\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
用于 Bedrock 模型的 AWS 凭据。
```bash theme={null}
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
```
**启用的模型**: Claude (Bedrock), Llama (Bedrock), Titan
### ZAI\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
ZAI API 密钥。
```bash theme={null}
ZAI_API_KEY=...
```
## 网页搜索提供商
### WEB\_SEARCH\_PROVIDER
**类型**: String
**默认值**: `google`
**有效值**: `google`, `serper`, `serpapi`, `searchapi`, `bing`, `exa`, `firecrawl`
**服务**: LLM Service
**热重载**: 是
活动的网页搜索提供商。
```bash theme={null}
WEB_SEARCH_PROVIDER=google
```
**提供商**:
* `searchapi` — SearchAPI.io — 多引擎搜索 (\$0.004/次调用)
### GOOGLE\_SEARCH\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
Google 自定义搜索 API 密钥。
```bash theme={null}
GOOGLE_SEARCH_API_KEY=...
GOOGLE_SEARCH_ENGINE_ID=...
```
获取地址: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)
### SERPER\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
Serper.dev API 密钥 (Google 搜索 API 替代方案)。
```bash theme={null}
SERPER_API_KEY=...
```
获取地址: [https://serper.dev](https://serper.dev)
### BING\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
Microsoft Bing 搜索 API 密钥。
```bash theme={null}
BING_API_KEY=...
```
### EXA\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
Exa AI 搜索 API 密钥。
```bash theme={null}
EXA_API_KEY=...
```
### FIRECRAWL\_API\_KEY
**类型**: String
**服务**: LLM Service
**热重载**: 是
用于网页抓取的 Firecrawl API 密钥。
```bash theme={null}
FIRECRAWL_API_KEY=...
```
### SEARCHAPI\_API\_KEY
**类型**: String
**必需**: 否
**默认值**: (无)
**服务**: LLM Service
**热重载**: 是
SearchAPI.io 的 API 密钥。在 [searchapi.io](https://www.searchapi.io) 获取。
```bash theme={null}
SEARCHAPI_API_KEY=...
```
## 数据存储
### PostgreSQL
#### POSTGRES\_HOST
**类型**: String
**默认值**: `postgres`
**服务**: Gateway, Orchestrator
**热重载**: 否
PostgreSQL 主机名。
```bash theme={null}
POSTGRES_HOST=postgres
```
#### POSTGRES\_PORT
**类型**: Integer
**默认值**: `5432`
**范围**: 1-65535
**服务**: Gateway, Orchestrator
**热重载**: 否
PostgreSQL 端口。
```bash theme={null}
POSTGRES_PORT=5432
```
#### POSTGRES\_DB
**类型**: String
**默认值**: `shannon`
**服务**: Gateway, Orchestrator
**热重载**: 否
PostgreSQL 数据库名称。
```bash theme={null}
POSTGRES_DB=shannon
```
#### POSTGRES\_USER
**类型**: String
**默认值**: `shannon`
**服务**: Gateway, Orchestrator
**热重载**: 否
PostgreSQL 用户名。
```bash theme={null}
POSTGRES_USER=shannon
```
#### POSTGRES\_PASSWORD
**类型**: String
**默认值**: `shannon`
**服务**: Gateway, Orchestrator
**热重载**: 否
PostgreSQL 密码。
```bash theme={null}
POSTGRES_PASSWORD=secure-password
```
**安全**: 生产环境中必须更改!
#### POSTGRES\_SSLMODE
**类型**: String
**默认值**: `disable`
**有效值**: `disable`, `require`, `verify-ca`, `verify-full`
**服务**: Gateway, Orchestrator
**热重载**: 否
PostgreSQL 连接的 SSL 模式。
```bash theme={null}
POSTGRES_SSLMODE=require
```
### Redis
#### REDIS\_HOST
**类型**: String
**默认值**: `redis`
**服务**: 所有
**热重载**: 否
Redis 主机名。
```bash theme={null}
REDIS_HOST=redis
```
#### REDIS\_PORT
**类型**: Integer
**默认值**: `6379`
**服务**: 所有
**热重载**: 否
Redis 端口。
```bash theme={null}
REDIS_PORT=6379
```
#### REDIS\_PASSWORD
**类型**: String
**默认值**: 空
**服务**: 所有
**热重载**: 否
Redis 密码 (如果启用了认证)。
```bash theme={null}
REDIS_PASSWORD=secure-password
```
#### REDIS\_TTL\_SECONDS
**类型**: Integer
**默认值**: `3600`
**范围**: 0-∞ (0 = 不过期)
**服务**: 所有
**热重载**: 是
Redis 键的默认 TTL。
```bash theme={null}
REDIS_TTL_SECONDS=3600
```
**影响**: 会话、事件、响应的缓存持续时间
#### REDIS\_URL
**类型**: String
**默认值**: `redis://redis:6379`
**服务**: 所有
**热重载**: 否
完整的 Redis 连接 URL。
```bash theme={null}
REDIS_URL=redis://redis:6379
# 带认证:
REDIS_URL=redis://:password@redis:6379
```
#### LLM\_REDIS\_URL
**类型**: String
**默认值**: 空 (使用 REDIS\_URL)
**服务**: LLM Service
**热重载**: 否
用于 LLM 响应缓存的专用 Redis 实例。
```bash theme={null}
LLM_REDIS_URL=redis://llm-redis:6379
```
**用例**: 将 LLM 缓存与会话数据分离以便扩展
### Qdrant (向量存储)
#### QDRANT\_URL
**类型**: String
**默认值**: `http://qdrant:6333`
**服务**: Orchestrator, LLM Service
**热重载**: 否
Qdrant 连接 URL。
```bash theme={null}
QDRANT_URL=http://qdrant:6333
```
#### QDRANT\_HOST / QDRANT\_PORT
**类型**: String / Integer
**默认值**: `qdrant` / `6333`
**服务**: Orchestrator, LLM Service
**热重载**: 否
QDRANT\_URL 的替代方案 (分别指定主机/端口)。
```bash theme={null}
QDRANT_HOST=qdrant
QDRANT_PORT=6333
```
## 服务端点
### TEMPORAL\_HOST
**类型**: String
**默认值**: `temporal:7233`
**服务**: Orchestrator
**热重载**: 否
Temporal 服务器地址。
```bash theme={null}
TEMPORAL_HOST=temporal:7233
```
### LLM\_SERVICE\_URL
**类型**: String
**默认值**: `http://llm-service:8000`
**服务**: Orchestrator, Agent Core
**热重载**: 否
LLM Service 端点。
```bash theme={null}
LLM_SERVICE_URL=http://llm-service:8000
```
### AGENT\_CORE\_ADDR
**类型**: String
**默认值**: `agent-core:50051`
**服务**: Orchestrator
**热重载**: 否
Agent Core gRPC 地址。
```bash theme={null}
AGENT_CORE_ADDR=agent-core:50051
```
### ORCHESTRATOR\_GRPC
**类型**: String
**默认值**: `orchestrator:50052`
**服务**: Gateway
**热重载**: 否
Orchestrator gRPC 端点。
```bash theme={null}
ORCHESTRATOR_GRPC=orchestrator:50052
```
### ADMIN\_SERVER
**类型**: String
**默认值**: `http://orchestrator:8081`
**服务**: Gateway
**热重载**: 否
用于流式事件的 Admin/SSE 服务器。
```bash theme={null}
ADMIN_SERVER=http://orchestrator:8081
```
### CONFIG\_PATH
**类型**: String
**默认值**: `./config/features.yaml`
**服务**: Orchestrator, Agent Core
**热重载**: 是 (带文件监视器)
功能标志配置的路径。
```bash theme={null}
CONFIG_PATH=./config/features.yaml
```
### MODELS\_CONFIG\_PATH
**类型**: String
**默认值**: `./config/models.yaml`
**服务**: LLM Service, Orchestrator
**热重载**: 是 (带文件监视器)
模型和定价配置的路径。
```bash theme={null}
MODELS_CONFIG_PATH=./config/models.yaml
```
### EVENTS\_INGEST\_URL
**类型**: String
**默认值**: `http://orchestrator:8081/events`
**服务**: Agent Core
**热重载**: 否
事件摄取端点。
```bash theme={null}
EVENTS_INGEST_URL=http://orchestrator:8081/events
```
## 模型路由和预算
### DEFAULT\_MODEL\_TIER
**类型**: String
**默认值**: `small`
**有效值**: `small`, `medium`, `large`
**服务**: Orchestrator
**热重载**: 是
任务的默认模型层级。
```bash theme={null}
DEFAULT_MODEL_TIER=small
```
**层级**:
* `small`: GPT-5-nano, Claude Haiku (\~\$0.15/1M tokens)
* `medium`: GPT-5-mini, Claude Sonnet (\~\$3-15/1M tokens)
* `large`: GPT-5.1, Claude Opus (\~\$15-75/1M tokens)
### COMPLEXITY\_MODEL\_ID
**类型**: String
**默认值**: `gpt-5`
**服务**: Orchestrator
**热重载**: 是
用于复杂度分析的模型。
```bash theme={null}
COMPLEXITY_MODEL_ID=gpt-5
```
### DECOMPOSITION\_MODEL\_ID
**类型**: String
**默认值**: `claude-sonnet-4-5-20250929`
**服务**: Orchestrator
**热重载**: 是
用于任务分解的模型。
```bash theme={null}
DECOMPOSITION_MODEL_ID=claude-sonnet-4-5-20250929
```
### MAX\_TOKENS
**类型**: Integer
**默认值**: `2000`
**范围**: 1-∞
**服务**: LLM Service
**热重载**: 是
每次 LLM 调用的默认最大输出Token数。
```bash theme={null}
MAX_TOKENS=2000
```
### TEMPERATURE
**类型**: Float
**默认值**: `0.7`
**范围**: 0.0-2.0
**服务**: LLM Service
**热重载**: 是
LLM 采样的默认温度。
```bash theme={null}
TEMPERATURE=0.7
```
**影响**:
* `0.0`: 确定性, 专注
* `0.7`: 平衡创造力
* `1.0+`: 更随机, 更有创意
### MAX\_TOKENS\_PER\_REQUEST
**类型**: Integer
**默认值**: `10000`
**范围**: 1-∞
**服务**: Orchestrator
**热重载**: 是
每个任务请求的最大总Token数。
```bash theme={null}
MAX_TOKENS_PER_REQUEST=10000
```
**影响**: 硬预算限制，超出时任务失败
### MAX\_COST\_PER\_REQUEST
**类型**: Float
**默认值**: `0.50`
**范围**: 0.0-∞
**服务**: Orchestrator
**热重载**: 是
每个任务请求的最大成本 (USD)。
```bash theme={null}
MAX_COST_PER_REQUEST=0.50
```
**影响**: 成本超出此限制时任务失败
### LLM\_DISABLE\_BUDGETS
**类型**: Integer
**默认值**: `1`
**有效值**: `0`, `1`
**服务**: Orchestrator, LLM Service
**热重载**: 是
预算执行位置。
```bash theme={null}
LLM_DISABLE_BUDGETS=1
```
**值**:
* `1`: Orchestrator 管理预算 (推荐)
* `0`: LLM service 执行预算
### HISTORY\_WINDOW\_MESSAGES
**类型**: Integer
**默认值**: `50`
**范围**: 1-∞
**服务**: Orchestrator
**热重载**: 是
对话历史中包含的消息数量。
```bash theme={null}
HISTORY_WINDOW_MESSAGES=50
```
### HISTORY\_WINDOW\_DEBUG\_MESSAGES
**类型**: Integer
**默认值**: `75`
**服务**: Orchestrator
**热重载**: 是
调试模式的历史窗口大小。
```bash theme={null}
HISTORY_WINDOW_DEBUG_MESSAGES=75
```
### WORKFLOW\_SYNTH\_BYPASS\_SINGLE
**类型**: Boolean
**默认值**: `true`
**服务**: Orchestrator
**热重载**: 是
跳过单结果工作流的综合。
```bash theme={null}
WORKFLOW_SYNTH_BYPASS_SINGLE=true
```
**影响**:
* `true`: 简单任务更快 (跳过综合步骤)
* `false`: 始终综合结果
### TOKEN\_BUDGET\_PER\_AGENT
**类型**: Integer
**默认值**: 空 (无限制)
**服务**: Orchestrator
**热重载**: 是
每次智能体执行的Token预算。
```bash theme={null}
TOKEN_BUDGET_PER_AGENT=5000
```
### TOKEN\_BUDGET\_PER\_TASK
**类型**: Integer
**默认值**: 空 (无限制)
**服务**: Orchestrator
**热重载**: 是
整个任务的Token预算。
```bash theme={null}
TOKEN_BUDGET_PER_TASK=20000
```
## 缓存和速率限制
### ENABLE\_CACHE
**类型**: Boolean
**默认值**: `true`
**服务**: LLM Service
**热重载**: 是
启用 LLM 响应缓存。
```bash theme={null}
ENABLE_CACHE=true
```
**影响**:
* `true`: 在 Redis 中缓存响应, 更快且更便宜
* `false`: 始终调用 LLM API
### CACHE\_SIMILARITY\_THRESHOLD
**类型**: Float
**默认值**: `0.95`
**范围**: 0.0-1.0
**服务**: LLM Service
**热重载**: 是
缓存命中的语义相似度阈值。
```bash theme={null}
CACHE_SIMILARITY_THRESHOLD=0.95
```
**影响**:
* `1.0`: 仅精确匹配
* `0.95`: 非常相似的查询
* `0.8`: 更宽松的匹配 (更多缓存命中, 准确性降低)
### RATE\_LIMIT\_REQUESTS
**类型**: Integer
**默认值**: `100`
**服务**: Gateway
**热重载**: 是
每个 API 密钥在每个窗口期内的请求数。
```bash theme={null}
RATE_LIMIT_REQUESTS=100
```
### RATE\_LIMIT\_WINDOW
**类型**: Integer
**默认值**: `60`
**范围**: 1-∞ (秒)
**服务**: Gateway
**热重载**: 是
速率限制窗口持续时间。
```bash theme={null}
RATE_LIMIT_WINDOW=60
```
**组合**:
```bash theme={null}
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60
# = 每 60 秒 100 个请求
```
### WEB\_SEARCH\_RATE\_LIMIT
**类型**: Integer
**默认值**: `120`
**服务**: LLM Service
**热重载**: 是
每分钟网页搜索请求数。
```bash theme={null}
WEB_SEARCH_RATE_LIMIT=120
```
### CALCULATOR\_RATE\_LIMIT
**类型**: Integer
**默认值**: `2000`
**服务**: LLM Service
**热重载**: 是
每分钟计算器工具请求数。
```bash theme={null}
CALCULATOR_RATE_LIMIT=2000
```
### PYTHON\_EXECUTOR\_RATE\_LIMIT
**类型**: Integer
**默认值**: `60`
**服务**: Agent Core
**热重载**: 是
每分钟 Python 代码执行请求数。
```bash theme={null}
PYTHON_EXECUTOR_RATE_LIMIT=60
```
### PARTIAL\_CHUNK\_CHARS
**类型**: Integer
**默认值**: `512`
**服务**: LLM Service
**热重载**: 是
每个流式块的字符数。
```bash theme={null}
PARTIAL_CHUNK_CHARS=512
```
## 工具执行和工作流
### TOOL\_PARALLELISM
**类型**: Integer
**默认值**: `1`
**范围**: 1-∞ (1 = 顺序执行)
**服务**: Orchestrator, Agent Core
**热重载**: 是
并发工具执行数。
```bash theme={null}
TOOL_PARALLELISM=1
```
**影响**:
* `1`: 顺序执行 (更慢, 更安全)
* `5`: 5 个工具并行 (更快, 更多资源)
* `10+`: 高并行度 (最快, 资源使用最高)
### ENABLE\_TOOL\_SELECTION
**类型**: Integer
**默认值**: `1`
**有效值**: `0`, `1`
**服务**: Orchestrator
**热重载**: 是
规划器自动选择工具。
```bash theme={null}
ENABLE_TOOL_SELECTION=1
```
**值**:
* `1`: 规划器自动选择工具 (推荐)
* `0`: 仅手动指定工具
### PRIORITY\_QUEUES
**类型**: String
**默认值**: `off`
**有效值**: `on`, `off`
**服务**: Orchestrator
**热重载**: 是
启用基于优先级的任务队列。
```bash theme={null}
PRIORITY_QUEUES=on
```
### STREAMING\_RING\_CAPACITY
**类型**: Integer
**默认值**: `1000`
**服务**: Orchestrator
**热重载**: 否
流式事件的环形缓冲区容量。
```bash theme={null}
STREAMING_RING_CAPACITY=1000
```
### COMPRESSION\_TRIGGER\_RATIO
**类型**: Float
**默认值**: `0.75`
**范围**: 0.0-1.0
**服务**: Orchestrator
**热重载**: 是
上下文压缩触发阈值。
```bash theme={null}
COMPRESSION_TRIGGER_RATIO=0.75
```
**影响**: 当使用了 75% 的Token预算时压缩上下文
### COMPRESSION\_TARGET\_RATIO
**类型**: Float
**默认值**: `0.375`
**范围**: 0.0-1.0
**服务**: Orchestrator
**热重载**: 是
压缩后的目标大小。
```bash theme={null}
COMPRESSION_TARGET_RATIO=0.375
```
### ENFORCE\_TIMEOUT\_SECONDS
**类型**: Integer
**默认值**: `90`
**服务**: Agent Core
**热重载**: 是
工具执行超时时间。
```bash theme={null}
ENFORCE_TIMEOUT_SECONDS=90
```
### ENFORCE\_MAX\_TOKENS
**类型**: Integer
**默认值**: `32768`
**服务**: Agent Core
**热重载**: 是
每次智能体执行的最大Token数。
```bash theme={null}
ENFORCE_MAX_TOKENS=32768
```
### ENFORCE\_RATE\_RPS
**类型**: Integer
**默认值**: `20`
**服务**: Agent Core
**热重载**: 是
智能体操作的速率限制 (每秒请求数)。
```bash theme={null}
ENFORCE_RATE_RPS=20
```
### ENFORCE\_CB\_ERROR\_THRESHOLD
**类型**: Float
**默认值**: `0.5`
**范围**: 0.0-1.0
**服务**: Agent Core
**热重载**: 是
断路器错误率阈值。
```bash theme={null}
ENFORCE_CB_ERROR_THRESHOLD=0.5
```
**影响**: 当 50% 的请求失败时断路器打开
### ENFORCE\_CB\_WINDOW\_SECONDS
**类型**: Integer
**默认值**: `30`
**服务**: Agent Core
**热重载**: 是
断路器测量窗口。
```bash theme={null}
ENFORCE_CB_WINDOW_SECONDS=30
```
### ENFORCE\_CB\_MIN\_REQUESTS
**类型**: Integer
**默认值**: `20`
**服务**: Agent Core
**热重载**: 是
断路器激活前的最小请求数。
```bash theme={null}
ENFORCE_CB_MIN_REQUESTS=20
```
## 审批和安全
### APPROVAL\_ENABLED
**类型**: Boolean
**默认值**: `false`
**服务**: Orchestrator
**热重载**: 是
启用人在回路审批。
```bash theme={null}
APPROVAL_ENABLED=true
```
### APPROVAL\_COMPLEXITY\_THRESHOLD
**类型**: Float
**默认值**: `0.5`
**范围**: 0.0-1.0
**服务**: Orchestrator
**热重载**: 是
需要审批的复杂度阈值。
```bash theme={null}
APPROVAL_COMPLEXITY_THRESHOLD=0.5
```
### APPROVAL\_DANGEROUS\_TOOLS
**类型**: String (逗号分隔)
**默认值**: `file_system,code_execution`
**服务**: Orchestrator
**热重载**: 是
需要审批的工具。
```bash theme={null}
APPROVAL_DANGEROUS_TOOLS=file_system,code_execution,database_query
```
### APPROVAL\_TIMEOUT\_SECONDS
**类型**: Integer
**默认值**: `1800`
**服务**: Orchestrator
**热重载**: 是
审批请求超时时间（30 分钟）。
```bash theme={null}
APPROVAL_TIMEOUT_SECONDS=1800
```
### JWT\_SECRET
**类型**: String
**默认值**: `development-only-secret-change-in-production`
**服务**: Gateway
**热重载**: 否
JWT 签名密钥。
```bash theme={null}
JWT_SECRET=secure-random-256-bit-key
```
**安全**: **生产环境中必须更改!**
### GATEWAY\_SKIP\_AUTH
**类型**: Integer
**默认值**: `1`
**有效值**: `0`, `1`
**服务**: Gateway
**热重载**: 是 (建议重启)
跳过认证 (仅限开发环境)。
```bash theme={null}
GATEWAY_SKIP_AUTH=0 # 启用认证
```
**安全**: **生产环境中必须设置为 `0`!**
## 模板
### TEMPLATE\_FALLBACK\_ENABLED
**类型**: Boolean
**默认值**: `false`
**服务**: Orchestrator
**热重载**: 是
模板失败时回退到 AI。
```bash theme={null}
TEMPLATE_FALLBACK_ENABLED=true
```
## 可观测性和遥测
### OTEL\_SERVICE\_NAME
**类型**: String
**默认值**: `shannon-llm-service`
**服务**: 所有
**热重载**: 否
OpenTelemetry 的服务名称。
```bash theme={null}
OTEL_SERVICE_NAME=shannon-llm-service
```
### OTEL\_EXPORTER\_OTLP\_ENDPOINT
**类型**: String
**默认值**: `localhost:4317`
**服务**: 所有
**热重载**: 否
OTLP 导出器端点。
```bash theme={null}
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
```
### OTEL\_ENABLED
**类型**: Boolean
**默认值**: `false`
**服务**: 所有
**热重载**: 否
启用 OpenTelemetry 追踪。
```bash theme={null}
OTEL_ENABLED=true
```
### LOG\_FORMAT
**类型**: String
**默认值**: `plain`
**有效值**: `plain`, `json`
**服务**: Agent Core (Rust)
**热重载**: 否
日志输出格式。
```bash theme={null}
LOG_FORMAT=json
```
### METRICS\_PORT
**类型**: Integer
**默认值**: `2112`
**服务**: 所有
**热重载**: 否
Prometheus 指标端口。
```bash theme={null}
METRICS_PORT=2112
```
## Python WASI 沙箱
### PYTHON\_WASI\_WASM\_PATH
**类型**: String
**默认值**: `./wasm-interpreters/python-3.11.4.wasm`
**服务**: Agent Core, LLM Service
**热重载**: 否
Python WASI 解释器的路径。
```bash theme={null}
PYTHON_WASI_WASM_PATH=./wasm-interpreters/python-3.11.4.wasm
```
### PYTHON\_WASI\_SESSION\_TIMEOUT
**类型**: Integer
**默认值**: `3600`
**服务**: LLM Service
**热重载**: 是
Python 会话超时时间 (秒)。
```bash theme={null}
PYTHON_WASI_SESSION_TIMEOUT=3600
```
### WASI\_MEMORY\_LIMIT\_MB
**类型**: Integer
**默认值**: `512`
**服务**: Agent Core
**热重载**: 是
WASI 沙箱内存限制 (MB)。
```bash theme={null}
WASI_MEMORY_LIMIT_MB=512
```
### WASI\_TIMEOUT\_SECONDS
**类型**: Integer
**默认值**: `60`
**服务**: Agent Core
**热重载**: 是
WASI 执行超时时间。
```bash theme={null}
WASI_TIMEOUT_SECONDS=60
```
## OpenAPI 和 MCP
### OpenAPI 集成
#### OPENAPI\_ALLOWED\_DOMAINS
**类型**: String
**默认值**: `*`
**服务**: LLM Service
**热重载**: 是
允许获取 OpenAPI 规范的域名。
```bash theme={null}
OPENAPI_ALLOWED_DOMAINS=*
# 或指定域名:
OPENAPI_ALLOWED_DOMAINS=api.example.com,api2.example.com
```
#### OPENAPI\_MAX\_SPEC\_SIZE
**类型**: Integer
**默认值**: `5242880` (5 MB)
**服务**: LLM Service
**热重载**: 是
OpenAPI 规范文件的最大大小。
```bash theme={null}
OPENAPI_MAX_SPEC_SIZE=5242880
```
#### OPENAPI\_FETCH\_TIMEOUT
**类型**: Integer
**默认值**: `30`
**服务**: LLM Service
**热重载**: 是
获取 OpenAPI 规范的超时时间。
```bash theme={null}
OPENAPI_FETCH_TIMEOUT=30
```
#### OPENAPI\_RETRIES
**类型**: Integer
**默认值**: `3`
**服务**: LLM Service
**热重载**: 是
OpenAPI 操作的重试次数（包括规范获取和 API 调用）。
```bash theme={null}
OPENAPI_RETRIES=3
```
### MCP 集成
#### MCP\_ALLOWED\_DOMAINS
**类型**: String
**默认值**: `*`
**服务**: LLM Service
**热重载**: 是
MCP 服务器允许的域名。
```bash theme={null}
MCP_ALLOWED_DOMAINS=*
```
#### MCP\_MAX\_RESPONSE\_BYTES
**类型**: Integer
**默认值**: `10485760` (10 MB)
**服务**: LLM Service
**热重载**: 是
MCP 响应的最大大小。
```bash theme={null}
MCP_MAX_RESPONSE_BYTES=10485760
```
#### MCP\_RETRIES
**类型**: Integer
**默认值**: `3`
**服务**: LLM Service
**热重载**: 是
MCP 请求重试次数。
```bash theme={null}
MCP_RETRIES=3
```
#### MCP\_TIMEOUT\_SECONDS
**类型**: Integer
**默认值**: `10`
**服务**: LLM Service
**热重载**: 是
MCP 请求超时时间。
```bash theme={null}
MCP_TIMEOUT_SECONDS=10
```
#### MCP\_REGISTER\_TOKEN
**类型**: String
**默认值**: 空
**服务**: LLM Service
**热重载**: 是
MCP 服务器注册的认证 Token。
```bash theme={null}
MCP_REGISTER_TOKEN=secret-token
```
#### MCP\_RATE\_LIMIT\_DEFAULT
**类型**: Integer
**默认值**: `60`
**服务**: LLM Service
**热重载**: 是
MCP 工具的默认速率限制 (请求数/分钟)。
```bash theme={null}
MCP_RATE_LIMIT_DEFAULT=60
```
#### MCP\_CB\_FAILURES
**类型**: Integer
**默认值**: `5`
**服务**: LLM Service
**热重载**: 是
MCP 的断路器失败阈值。
```bash theme={null}
MCP_CB_FAILURES=5
```
#### MCP\_CB\_RECOVERY\_SECONDS
**类型**: Integer
**默认值**: `60`
**服务**: LLM Service
**热重载**: 是
断路器恢复时间。
```bash theme={null}
MCP_CB_RECOVERY_SECONDS=60
```
#### MCP\_COST\_TO\_TOKENS
**类型**: Integer
**默认值**: `0`
**服务**: LLM Service
**热重载**: 是
MCP 工具的Token成本乘数。
```bash theme={null}
MCP_COST_TO_TOKENS=100
```
## 高级 Orchestrator 控制
### EVENTLOG\_BATCH\_SIZE
**类型**: Integer
**默认值**: `100`
**服务**: Orchestrator
**热重载**: 是
数据库写入的每批事件数。
```bash theme={null}
EVENTLOG_BATCH_SIZE=100
```
### EVENTLOG\_BATCH\_INTERVAL\_MS
**类型**: Integer
**默认值**: `100`
**服务**: Orchestrator
**热重载**: 是
批处理间隔 (毫秒)。
```bash theme={null}
EVENTLOG_BATCH_INTERVAL_MS=100
```
### RATE\_LIMIT\_INTERVAL\_MS
**类型**: Integer
**默认值**: `60000`
**服务**: Orchestrator
**热重载**: 是
速率限制窗口 (毫秒)。
```bash theme={null}
RATE_LIMIT_INTERVAL_MS=60000
```
### Worker 并发
配置每个优先级队列的 Temporal worker 并发数:
```bash theme={null}
# 默认 workers (所有优先级)
WORKER_ACT=10
WORKER_WF=10
# 关键优先级
WORKER_ACT_CRITICAL=12
WORKER_WF_CRITICAL=12
# 高优先级
WORKER_ACT_HIGH=10
WORKER_WF_HIGH=10
# 普通优先级
WORKER_ACT_NORMAL=8
WORKER_WF_NORMAL=8
# 低优先级
WORKER_ACT_LOW=4
WORKER_WF_LOW=4
```
**影响**:
* 更高的值 = 更高的并发, 更多的资源使用
* 更低的值 = 更低的并发, 更少的资源使用
### LLM\_TIMEOUT\_SECONDS
**类型**: Integer
**默认值**: `120`
**服务**: Orchestrator
**热重载**: 是
LLM API 调用的超时时间。
```bash theme={null}
LLM_TIMEOUT_SECONDS=120
```
## 杂项
### SHANNON\_WORKSPACE
**类型**: String
**默认值**: `./workspace`
**服务**: Agent Core
**热重载**: 否
文件操作的工作区目录。
```bash theme={null}
SHANNON_WORKSPACE=./workspace
```
### SHANNON\_SESSION\_WORKSPACES\_DIR
**类型**: String
**默认值**: `/tmp/shannon-sessions`
**服务**: Gateway, Agent Core
**热重载**: 否
会话隔离工作区文件的基础目录。每个会话会获得一个子目录。
```bash theme={null}
SHANNON_SESSION_WORKSPACES_DIR=/tmp/shannon-sessions
```
### SHANNON\_USE\_WASI\_SANDBOX
**类型**: Boolean (0/1)
**默认值**: `0`
**服务**: Agent Core
**热重载**: 否
启用文件操作的 WASI 沙箱。启用后，文件访问将通过 Firecracker 执行器进行安全隔离。
```bash theme={null}
SHANNON_USE_WASI_SANDBOX=1
```
### SHANNON\_MAX\_WORKSPACE\_SIZE\_MB
**类型**: Integer
**默认值**: `100`
**服务**: Agent Core
**热重载**: 否
每个会话工作区的最大磁盘配额（MB）。
```bash theme={null}
SHANNON_MAX_WORKSPACE_SIZE_MB=100
```
### SEED\_DATA
**类型**: Boolean
**默认值**: `false`
**服务**: 所有
**热重载**: 否
启动时在 Qdrant 中填充示例数据。
```bash theme={null}
SEED_DATA=true
```
### AGENT\_TIMEOUT\_SECONDS
**类型**: Integer
**默认值**: `600`
**服务**: Agent Core
**热重载**: 是
每次智能体执行的最大运行时间。
```bash theme={null}
AGENT_TIMEOUT_SECONDS=600
```
## 配置示例
### 开发环境
```bash theme={null}
ENVIRONMENT=dev
DEBUG=true
GATEWAY_SKIP_AUTH=1
ENABLE_CACHE=true
DEFAULT_MODEL_TIER=small
MAX_COST_PER_REQUEST=0.10
TOOL_PARALLELISM=3
```
### 生产环境
```bash theme={null}
ENVIRONMENT=prod
DEBUG=false
GATEWAY_SKIP_AUTH=0
JWT_SECRET=
POSTGRES_PASSWORD=
REDIS_PASSWORD=
ENABLE_CACHE=true
DEFAULT_MODEL_TIER=medium
MAX_COST_PER_REQUEST=1.00
TOOL_PARALLELISM=5
OTEL_ENABLED=true
LOG_FORMAT=json
```
### 高性能
```bash theme={null}
TOOL_PARALLELISM=10
WORKER_ACT_CRITICAL=30
WORKER_WF_CRITICAL=15
ENABLE_CACHE=true
CACHE_SIMILARITY_THRESHOLD=0.90
STREAMING_RING_CAPACITY=2000
```
### 成本优化
```bash theme={null}
DEFAULT_MODEL_TIER=small
MAX_COST_PER_REQUEST=0.25
MAX_TOKENS_PER_REQUEST=5000
ENABLE_CACHE=true
CACHE_SIMILARITY_THRESHOLD=0.95
WORKFLOW_SYNTH_BYPASS_SINGLE=true
```
## 故障排除
有关常见问题，请参阅 [配置故障排除](/cn/deployment/configuration-troubleshooting)。
## 相关文档
Docker 部署指南
Kubernetes 部署
优化性能
安全加固