运行时环境变量

workflow 代码统一通过 workflow.getEnv(name) 读取配置。不要直接依赖某个平台专属的配置读取方式。

const apiKey = workflow.getEnv("EXAMPLE_API_KEY");

来源顺序

不同运行位置的值来源不同：

运行位置	配置来源
终端 / CLI	workflow 目录 `.env`，然后 process env。
Desktop	本地项目保存的环境变量配置。
Workflow Server	server 侧保存的 workflow 环境变量配置。

server 启动时还会加载 server/.env 和项目根目录 .env。shell 已存在的环境变量优先，.env 只补充缺失项。

Desktop 本地环境变量

Desktop 的 Env 按钮管理本地运行变量。保存后，下一次本地运行会在 executor context 中读到这些值。Desktop 本地变量不会自动保存到 server draft，也不会影响已发布版本。

Server 环境变量

Server Web 的环境变量页面管理远程运行使用的配置。server run、external API、Embed 和 Webhook 都读取 server 侧变量。密钥类变量应只写入服务端配置，不应出现在公开页面、日志或文档示例中。

LLM Provider 环境变量

workflow.createLLMProviderFromEnv() 默认读取：

LLM_TYPE
LLM_API_KEY
LLM_BASE_URL
LLM_MODEL

这些变量同样通过 workflow.getEnv 进入 provider。

Conversation、Codex 和 OpenCode 内置项目不读取这些 provider 环境变量，而是使用当前登录账户的系统 AI 配置。OpenCode 也不会读取 OPENCODE_PROVIDER_*、用户全局 OpenCode 配置或 opencode auth login 状态。

第三方服务调用

非 LLM 的第三方调用建议在 workflow 中直接使用 fetch 或业务 SDK，并通过 workflow.getEnv 读取密钥：

const response = await fetch("https://api.example.com/run", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${workflow.getEnv("EXAMPLE_API_KEY") ?? ""}`,
  },
  body: JSON.stringify({ input }),
});

示例 workflow

示例 workflow 可以把自己的 SDK 声明为项目依赖，并通过环境变量读取凭据：

示例	常用变量	说明
`openai-agents`	`OPENAI_API_KEY`、`OPENAI_BASE_URL`	调用 OpenAI Agents SDK，可按示例启用本地工具。
`claude-agent`	`ANTHROPIC_API_KEY`	调用 Claude Agent SDK，并可按 conversation 复用 session。
`pi-agent`	`ANTHROPIC_`、`OPENAI_`	通过 Advanced options 切换 provider，并可使用项目知识库工具。
`opencode`	无 provider 环境变量	从当前登录账户的系统 AI 配置选择 Provider 和 Model。
`gpt-image`	`OPENAI_API_KEY`、`OPENAI_BASE_URL`	调用图片生成能力，并把结果作为 output item 展示。

本地终端可以把变量放在示例目录 .env；Desktop 和 server run 则从各自保存的 workflow 环境变量中注入。需要真实外部服务的示例应提供 dry-run 或 opt-in smoke，避免默认测试依赖远程平台。

来源顺序​

Desktop 本地环境变量​

Server 环境变量​

LLM Provider 环境变量​

第三方服务调用​

示例 workflow​