环境变量

环境变量用于控制 SkillFlaw 的整体运行方式，例如监听地址、数据库连接、缓存类型、日志输出和认证行为。 像 SKILLFLAW_PORT、SKILLFLAW_LOG_LEVEL、SKILLFLAW_DATABASE_URL 这类变量，都会影响整个部署实例。

与之相对，全局变量是保存在 SkillFlaw 数据库中的用户级值，主要供流程或组件使用，例如 OPENAI_API_KEY。

为 SkillFlaw OSS 配置环境变量

SkillFlaw 会从以下来源读取支持的环境变量：

• 当前终端会话中显式设置的环境变量
• 使用 --env-file 或等价方式导入的 .env 文件
• CLI 直接传入的参数，例如 skillflaw run --port 9000

优先级

如果同一个变量在多个地方都被设置，优先级如下：

1. CLI 直接参数优先级最高
2. .env 文件高于系统环境变量
3. 系统环境变量只在没有更高优先级来源时生效

例如：

• 如果系统环境中设置了 SKILLFLAW_PORT=8080，而 .env 中设置了 SKILLFLAW_PORT=7860，那么最终会使用 7860
• 如果你执行 skillflaw run --env-file .env --port 9000，那么最终会使用 9000

在终端中设置环境变量

Linux or macOS

_10

export VARIABLE_NAME='VALUE'

Windows

_10

set VARIABLE_NAME=VALUE

启动 SkillFlaw 时，进程会读取这些已设置的变量，并按优先级规则决定最终生效值。

从 .env 文件导入环境变量

1. 如果 SkillFlaw 正在运行，请先停止它。

2. 在源码工作区根目录复制模板：

   
   

   _10

   cp .env.example .env

   
   

3. 按当前环境填写 .env。

4. 使用 .env 启动 SkillFlaw：

   
   

   _10

   uv run skillflaw run --env-file .env

   
   

推荐模板是项目根目录的 .env.example。 相比旧式纯文本写法，更推荐使用 SKILLFLAW_SECRET_KEY_FILE 管理密钥文件，而不是只依赖 SKILLFLAW_SECRET_KEY 纯文本值。

一个面向本地开发的最小示例如下：

_13

SKILLFLAW_CONFIG_DIR=~/.skillflaw

_13

SKILLFLAW_SECRET_KEY_FILE=~/.skillflaw/secret_key

_13

SKILLFLAW_DATABASE_URL=postgresql://postgres:password@localhost:5432/skillflaw

_13

SKILLFLAW_CONFIG_MODEL=local

_13

SKILLFLAW_CACHE_TYPE=async

_13

SKILLFLAW_HOST=localhost

_13

SKILLFLAW_PORT=7860

_13

SKILLFLAW_LOG_LEVEL=info

_13

SKILLFLAW_ENABLE_SUPERUSER_CLI=False

_13

SKILLFLAW_SUPERUSER=administrator

_13

SKILLFLAW_SUPERUSER_PASSWORD=securepassword

_13

SKILLFLAW_API_KEY_SOURCE=db

_13

SKILLFLAW_STORE_ENVIRONMENT_VARIABLES=True

开发环境中的常见配置方式

.env file

最常见的做法是在源码工作区根目录维护 .env，再通过 --env-file 或 make 封装命令启动。

这也是最常见的本地开发方式。

Systemd service

如果你在 Linux 服务器上把 SkillFlaw 作为 systemd 服务运行，可以在服务覆盖文件中定义环境变量：

_10

[Service]

_10

Environment="SKILLFLAW_CONFIG_DIR=/srv/skillflaw/config"

_10

Environment="SKILLFLAW_SECRET_KEY_FILE=/srv/skillflaw/config/secret_key"

_10

Environment="SKILLFLAW_DATABASE_URL=postgresql://postgres:password@localhost:5432/skillflaw"

_10

Environment="SKILLFLAW_HOST=0.0.0.0"

_10

Environment="SKILLFLAW_PORT=7860"

_10

Environment="SKILLFLAW_LOG_LEVEL=info"

VSCode tasks.json

如果你在 VS Code 中通过任务启动 SkillFlaw，可以在 .vscode/tasks.json 中声明 options.env：

_21

{

_21

"version": "2.0.0",

_21

"options": {

_21

"env": {

_21

"SKILLFLAW_CONFIG_DIR": "/Users/your_user/.skillflaw",

_21

"SKILLFLAW_SECRET_KEY_FILE": "/Users/your_user/.skillflaw/secret_key",

_21

"SKILLFLAW_DATABASE_URL": "postgresql://postgres:password@localhost:5432/skillflaw",

_21

"SKILLFLAW_HOST": "localhost",

_21

"SKILLFLAW_PORT": "7860"

_21

}

_21

},

_21

"tasks": [

_21

{

_21

"label": "skillflaw backend",

_21

"type": "shell",

_21

"command": "uv run skillflaw run --env-file .env",

_21

"isBackground": true,

_21

"problemMatcher": []

_21

}

_21

]

_21

}

为 SkillFlaw Desktop 配置环境变量

通过图形界面启动的桌面应用，通常不会自动继承你在终端中临时设置的环境变量。 因此，如果你使用 SkillFlaw Desktop，需要按操作系统分别处理。

macOS

从 Finder、Spotlight、Launchpad 或 Dock 启动的 macOS GUI 应用，不会自动继承 .zshrc 或 .bash_profile 中的变量。

可以使用 launchctl 配合 plist 文件注入变量：

1. 创建目录：

   
   

   _10

   mkdir -p ~/Library/LaunchAgents

   
   

2. 创建 ~/Library/LaunchAgents/dev.skillflaw.env.plist

3. 填入类似如下内容：

   
   

   _22

   <?xml version="1.0" encoding="UTF-8"?>

   _22

   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

   _22

   <plist version="1.0">

   _22

   <dict>

   _22

   <key>Label</key>

   _22

   <string>dev.skillflaw.env</string>

   _22

   <key>ProgramArguments</key>

   _22

   <array>

   _22

   <string>/bin/sh</string>

   _22

   <string>-c</string>

   _22

   <string>

   _22

   launchctl setenv SKILLFLAW_CONFIG_DIR /Users/your_user/.skillflaw ;

   _22

   launchctl setenv SKILLFLAW_SECRET_KEY_FILE /Users/your_user/.skillflaw/secret_key ;

   _22

   launchctl setenv SKILLFLAW_PORT 7860 ;

   _22

   launchctl setenv SKILLFLAW_HOST localhost ;

   _22

   launchctl setenv OPENAI_API_KEY sk-...

   _22

   </string>

   _22

   </array>

   _22

   <key>RunAtLoad</key>

   _22

   <true/>

   _22

   </dict>

   _22

   </plist>

   
   

4. 加载该文件：

   
   

   _10

   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.skillflaw.env.plist

   
   

Windows 系统属性

在 Windows 上，从开始菜单、桌面快捷方式或资源管理器启动的 GUI 应用，也不会自动继承你在终端里临时设置的变量。

你可以通过系统属性界面为当前用户或整台机器设置变量：

1. 按 Win + R
2. 输入 SystemPropertiesAdvanced
3. 打开 Environment Variables
4. 在 User variables 或 System variables 中添加所需的 SKILLFLAW_* 变量
5. 重新启动 SkillFlaw Desktop

PowerShell

你也可以用 PowerShell 直接写入用户级或系统级环境变量：

_10

[System.Environment]::SetEnvironmentVariable("SKILLFLAW_CONFIG_DIR", "C:\Users\your_user\.skillflaw", "User")

_10

[System.Environment]::SetEnvironmentVariable("SKILLFLAW_SECRET_KEY_FILE", "C:\Users\your_user\.skillflaw\secret_key", "User")

设置后，重新启动 SkillFlaw Desktop 即可生效。

支持的环境变量

环境变量数量较多，而且会随版本演进。 因此，最稳妥的做法是：

1. 以项目提供的 .env.example 为参考模板
2. 结合下列分类页面理解变量语义

认证与安全

请参阅 API Key 与认证。

全局变量

关于环境变量与全局变量之间的关系，以及从环境导入全局变量的能力，请参阅全局变量。

日志

请参阅日志。

MCP 服务器

请参阅将 SkillFlaw 用作 MCP 服务器。

监控与遥测

监控服务商自己的接入变量，请参阅对应集成文档，例如 Langfuse。 遥测说明请参阅遥测。

常用环境变量分类

服务基础配置

变量	类型	说明
SKILLFLAW_CONFIG_DIR	String	SkillFlaw 配置目录；若未显式指定密钥文件，默认也会在该目录下生成 secret_key
SKILLFLAW_SECRET_KEY_FILE	String	推荐的密钥文件路径，运行时读取文件内容作为 secret key
SKILLFLAW_DATABASE_URL	String	PostgreSQL 连接地址；SkillFlaw 运行依赖 PostgreSQL
SKILLFLAW_CONFIG_MODEL	String	运行时配置来源模型，例如 local、from_db、update_db
SKILLFLAW_HOST	String	服务监听地址
SKILLFLAW_PORT	Integer	服务监听端口
SKILLFLAW_WORKERS	Integer	Worker 进程数
SKILLFLAW_LOG_LEVEL	String	日志级别
SKILLFLAW_FRONTEND_PATH	String	前端构建产物目录路径

缓存与性能

变量	类型	说明
SKILLFLAW_CACHE_TYPE	String	内部缓存类型，例如 async、memory、redis
SKILLFLAW_LANGCHAIN_CACHE	String	LangChain 缓存类型
SKILLFLAW_REDIS_HOST	String	Redis 主机
SKILLFLAW_REDIS_PORT	Integer	Redis 端口
SKILLFLAW_REDIS_DB	Integer	Redis 数据库编号
SKILLFLAW_REDIS_CACHE_EXPIRE	Integer	Redis 缓存过期时间

可视化编辑器与运行时行为

变量	类型	说明
SKILLFLAW_OPEN_BROWSER	Boolean	启动后是否自动打开浏览器
SKILLFLAW_REMOVE_API_KEYS	Boolean	保存流程前是否移除 API Key / Token 类敏感字段
SKILLFLAW_STORE_ENVIRONMENT_VARIABLES	Boolean	是否把环境变量导入为全局变量
SKILLFLAW_FALLBACK_TO_ENV_VAR	Boolean	当全局变量缺失时，是否回退读取同名环境变量
SKILLFLAW_COMPONENTS_PATH	String	自定义组件目录

认证相关

变量	类型	说明
SKILLFLAW_ENABLE_SUPERUSER_CLI	Boolean	是否允许通过 CLI 创建超级用户
SKILLFLAW_SUPERUSER	String	引导超级用户名
SKILLFLAW_SUPERUSER_PASSWORD	String	引导超级用户密码
SKILLFLAW_API_KEY_SOURCE	String	API Key 校验来源：db / env
SKILLFLAW_API_KEY	String	当 API_KEY_SOURCE=env 时使用的 API Key
SKILLFLAW_WEBHOOK_AUTH_ENABLE	Boolean	是否要求 Webhook 强制使用 API Key

另请参阅

• 本地开发部署
• 全局变量
• API Key 与认证
• 内存管理选项