环境变量
面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/worker-env/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。
当 Agent 在 Agent Computer Worker 上执行终端命令、调用外部 MCP 服务或运行后台 Agent 任务时,往往需要读取第三方服务的 API Key、访问令牌或接口地址。请统一在 Console 的“环境变量”页面托管这些配置,切勿将敏感凭据硬编码进 Skill 文档、Agent 人设文件或日常聊天消息中。
配置的环境变量会注入 Agent 执行工具及其拉起的子进程:每次运行命令时,系统都会构造一份仅包含这些显式变量的干净环境变量表,不会把 Worker 守护进程自身的宿主环境原盘泄漏给子进程。注意,此处仅用于存放供 Agent 工具脚本消费的业务凭据;模型提供商、身份源提供商与聊天渠道自身的接入密钥,请前往各自专属的 Console 管理页面配置。
远程 HTTP MCP 依赖的凭据由控制面代理读取:bearer_token_env_var 引用的密钥会从 Worker 环境快照中排除,Worker 使用内部回合令牌访问代理。内置连接器的应用凭据与个人 OAuth 授权在 Pod「外部连接」页面管理。其他自定义命令变量按下述规则注入。
先选择作用范围
| 适用对象 | 配置入口 | 作用域优先级 |
|---|---|---|
| 整站所有 Agent | Console → 环境变量 → 新建站点变量 | 站点级全局默认值 |
| 某一租户下的全部 Agent | Console → 选择租户 → 环境变量 → 新建租户变量 | 在当前租户内覆盖站点默认值 |
| 指定的单个 Agent | Console → 智能体 → 选择 Agent → 环境变量 | 为该 Agent 单独覆盖租户值与站点默认值 |
运行时按“单 Agent 覆盖值 → 租户级变量 → 站点默认值”的优先级从高到低依次查找:一旦清除上层覆盖值,便自动回退读取下一级配置;若三级作用域均未定义某变量,则不会向进程环境注入该键。
添加站点或租户变量
- 打开 Console → 环境变量,切换至目标租户上下文,按需点击“新建站点变量”或“新建租户变量”。
- 填写变量名:仅允许使用英文字母、数字与下划线,且不得以数字开头(例如
MY_API_KEY)。 - 填入变量值:凡涉及 API Key、访问令牌、密码等敏感信息,请务必保持“加密存储”处于开启状态。
- 按需填写用途备注,注明该变量供哪个工具或外部服务调用(备注仅在管理后台展示,不会下发给 Agent)。
- 点击保存。
以下名称归底层运行环境保留使用,禁止在此处自定义覆盖:PATH、HOME、SHELL、TERM、LANG、BASH_ENV、ENV、WORKER_ID、DATABASE_URL、CODEX_UNSAFE_ALLOW_NO_SANDBOX,以及所有以 ANKOLE_ 开头的变量名。
只为一个 Agent 设置变量
- 打开 Console → 智能体 页面,点开目标 Agent。
- 定位到“环境变量”配置区。
- 点击添加新变量,或在已有继承变量行末点击“覆盖”。
- 填入专属变量值并保存。
该面板会直观汇总展示站点默认值、当前租户值与单 Agent 覆盖值,并通过“来源”列标明当前实际生效的值取自哪一层级。点击“清除”只会删掉当前 Agent 的专属覆盖值,使其恢复继承租户值或站点默认值。
看懂变量类型
环境变量列表(WorkerEnv)中的所有条目均由运维人员按需手动维护——Ankole 核心系统及控制面插件绝不会借道 WorkerEnv 向外暴露内部 AppConfigure 系统配置,而运行时保留环境变量与信号路由绑定凭据则分别由各自所属的子系统独立管理。
加密、查看与轮换
新建环境变量时默认自动勾选“加密存储”:落库加密后,Console 列表页面上始终仅显示掩码占位符,而在 Worker 端实际拉起命令时则会解密还原为明文注入子进程环境。
编辑已加密的变量时,若保持输入框内的掩码不动直接保存,服务端会继续保留原密文不变;日常轮换密钥时,只需直接输入新密钥保存即可覆盖,无需先解密查看旧值。
请仅在排查线上故障、确有必要核实当前生效内容时才点击“查看”。若取消勾选“加密存储”改为明文保存,Console 会弹窗要求二次确认——任何 API Key、访问令牌与密码均严禁关闭加密保护。
什么时候生效
保存或更新环境变量后,新值会从后续新启动的 Worker 任务与工作区开始生效,此前已经拉起并捕获了旧环境的在途进程或已打开工作区则会继续沿用启动时的原值。此外,主对话的模型推理循环直接运行在控制面内,不会把 WorkerEnv 当作控制面自身的操作系统进程环境。
如果发现 Agent 未能读取到预期的环境变量值,请按以下顺序逐一核查:
- 核对变量拼写是否与 Skill 文档、脚本源码或
bearer_token_env_var中声明的名称完全一致(严格区分大小写); - 按“单 Agent 覆盖 → 租户级 → 站点默认值”顺序排查是否存在预期之外的上层覆盖;
- 确认三级作用域中至少有一层已成功保存非空值;
- 修改配置后请触发新的 Worker 执行任务验证,不要在保存前便已建立的旧工作区里测试。
为挂载 MCP 的 Skill 配置鉴权时,openai.yaml 的 bearer_token_env_var 字段中只填写环境变量名称,真正的令牌明文正是存放在本页面中。具体声明规范见 MCP。