​
运行时环境变量

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

​
来源顺序

不同运行位置的值来源不同：
  • 终端/CLI：workflow 目录 .env，然后 process env。
  • 桌面 App：本地项目保存的环境变量配置。
  • Workflow Server：server 侧保存的 workflow 环境变量配置。
server 启动时还会加载 server/.env 和仓库根目录 .env。shell 已存在的环境变量优先，.env 只补充缺失项。

​
App 本地环境变量

App 的 Env 按钮管理本地 dev 环境变量。实现上会调用 Electron 的 readLocalProjectEnvConfig 和 saveLocalProjectEnvConfig，不会保存到 server draft。 保存本地变量后，下一次本地运行会在 executor context 中读到这些值。

​
Server 环境变量

server web 的环境变量页面会读取指定 target 的配置，并保存到 server storage。server 运行、外部 API、embed 和 webhook 都会使用 server 侧变量。

​
LLM Provider 环境变量

workflow.createLLMProviderFromEnv() 当前读取：
  • LLM_TYPE
  • LLM_API_KEY
  • LLM_BASE_URL
  • LLM_MODEL
这些变量同样通过 workflow.getEnv 进入 provider。

​
外部系统调用

非 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 }),
});
第三方 SDK 也遵循同一规则。workspace/workflow/openai-agents 示例把 @openai/agents 声明为 workflow 自己的 npm dependency，并在 live run 中读取 OPENAI_API_KEY 和可选的 OPENAI_BASE_URL 后调用 SDK： 
const apiKey = workflow.getEnv("OPENAI_API_KEY");
const baseURL = workflow.getEnv("OPENAI_BASE_URL");
if (apiKey === undefined) {
  throw new workflow.WorkflowError({
    type: "input_validation",
    message: "OPENAI_API_KEY is required.",
  });
}
setDefaultOpenAIClient(new OpenAI({ apiKey, baseURL }));
同一示例还可通过 --local-shell 演示 Agents SDK 的 shellTool 本地模式。 shellTool 本身只定义 tool 协议，真正执行本地命令的是 workflow 提供的 shell.run(...) 实现；示例把命令限制在 --workdir 内，并对危险命令、写 重定向、超时和输出长度做基础防护。部分 OpenAI-compatible base URL 可能尚未 支持 Responses API shell tool，因此该能力需要显式开启。 该示例还包含自定义 test_tool function tool。它通过 workflow 代码发起小型 HTTP GET/POST 请求，并把 status、content type 和短响应预览返回给 Agent； 离线测试使用本地 HTTP server 覆盖真实请求路径，不需要真实外网服务。 workspace/workflow/claude-agent 示例把 @anthropic-ai/claude-agent-sdk 声明为 workflow 自己的 npm dependency，并通过 ANTHROPIC_API_KEY 运行真实 Claude Agent 会话。该示例会把 Claude Agent session id 写入 context.conversation，后续相同 conversation id 的运行会 resume 同一个 SDK session；tool activity 会作为折叠 output item 流式展示。 workspace/workflow/pi-agent 示例把 @earendil-works/pi-coding-agent 声明为 workflow 自己的 npm dependency，并通过 Pi SDK 的 createAgentSession 运行 agent turn。它的 Advanced options 暴露 --provider 切换，支持 anthropic 与 openai；运行时会读取 ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL / ANTHROPIC_MODEL 或 OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL，并兼容 OPENAPI_* 作为 OpenAI 拼写别名。 Pi Agent 正文会作为 inline Output 分段展示，工具调用则作为 metadata-backed detail item 穿插在对应正文段之间。它还注册同名 knowledge_documents custom tool，复用项目 PersistentValue-backed knowledge documents，默认启用并可通过 --no-knowledge-tools 关闭。普通运行默认调用真实 Pi SDK provider；普通测试显式传 --dry-run，避免依赖远程 provider。 workspace/workflow/gpt-image 示例直接使用 openai SDK 的 Images API。 它开启 conversation 模式，会把最近几轮对话摘要合并进本轮图片 prompt，再优先读取 OPENAI_API_KEY / OPENAI_BASE_URL，也兼容 LLM_API_KEY / LLM_BASE_URL； 默认测试通过 mock image runner 离线返回 data URL，真实图片生成只按示例 README 中的 opt-in 命令运行。 本地终端可以把这些变量放在示例目录 .env；App 和 server run 则继续从 各自保存的 workflow 环境变量中注入。openai-agents 和 claude-agent 的真实 SDK 调用都是 live-only，普通测试只覆盖结构契约，不会默认调用真实 OpenAI 或 Claude Agent SDK；pi-agent 普通运行也是 live by default，但测试 fixture 会显式开启 dry-run session；gpt-image 普通测试通过 mock image runner 覆盖参数解析、 conversation 上下文和 output item。

​
追踪

本文档首版由 issue #32 记录。环境变量行为对齐 core/env.ts、server/src/env.ts、app/src/renderer/src/store/index.ts 和 core/provider/llm/factory.ts。