background-agents 密钥保留键与限制完整指南这些坑一次说清楚【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agentsbackground-agentsOpen-Inspect是一款开源的后台智能体background agents编码系统会话所用的 API 密钥、数据库连接串都以密钥Secrets形式注入沙箱。但新手最常卡在两处17 个保留键无法自行设置、6 条硬性限制会直接导致会话创建失败。本文基于官方文档与校验源码把保留键清单、限制数值和 5 个高频坑一次讲透帮你避免密钥存了却用不了的尴尬。界面左下角的Manage secrets and settings就是密钥管理入口所有密钥都在那里配置。一、30 秒建立心智模型密钥的三个作用域在谈保留键之前先搞清楚密钥存在哪里这是后续所有坑的前提 作用域生效范围典型例子全局Global所有会话ANTHROPIC_API_KEY仓库Repository该仓库发起的会话STRIPE_SECRET_KEY环境Environment该环境发起的会话多仓库共享凭证优先级规则仓库/环境密钥覆盖同名全局密钥多仓库会话撞键时主仓库列表第一个获胜。特别注意从环境发起的会话只拿全局 环境密钥环境里的各仓库密钥不会自动流入——这是新手最常问的问题。二、17 个保留键全清单为什么你不能自己设保留键是为系统运行预留的控制平面会在沙箱启动时自行注入因此禁止用户覆盖。完整清单如下按用途分组更好记分组保留键沙箱与运行配置PYTHONUNBUFFERED、SANDBOX_ID、CONTROL_PLANE_URL、SANDBOX_AUTH_TOKEN、SESSION_CONFIG、RESTORED_FROM_SNAPSHOT、OPENCODE_CONFIG_CONTENT仓库与 SCM 身份REPO_OWNER、REPO_NAME、GITHUB_APP_TOKEN标准 shell 环境变量PATH、HOME、USER、SHELL、TERM、PWD、LANG校验逻辑对保留键是大小写不敏感的path、Path、PATH一律被拒。前后端各有一份相同的清单可在 secrets-validation.ts后端与 secrets-editor.tsx前端 UI中对照查看。三、6 条硬性限制数量、长度与大小上限约束上限每个作用域最多密钥数50 个键名最大长度256 字符单个值最大体积16 KB单个作用域值总大小64 KB单次会话合并后总大小128 KB全局 会话目标合并后键名格式[A-Za-z_][A-Za-z0-9_]*字母/下划线开头仅字母、数字、下划线最容易被忽视的是128 KB 合并上限多仓库会话会把多个仓库的密钥折叠进同一个沙箱一旦超限创建会话直接失败并且报错会按作用域列出各自占用的字节数如global (8192 bytes, 3 keys)告诉你该去哪个作用域瘦身。这一逻辑实现在 secrets-validation.ts 中。四、最容易踩的 5 个坑含解法1️⃣ 保留键校验不分大小写想存个path之类的键会被直接拒绝。完整用例可见 secrets-validation.test.ts。换个名字如CUSTOM_PATH_EXTRA即可。2️⃣ 键名会被自动转成大写保存my_api_key会自动变成MY_API_KEY。注意键名不能以数字开头、不能用连字符1BAD、FOO-BAR都是非法键名。3️⃣ 新密钥只对新沙箱生效保存密钥后旧会话不会自动拿到必须重启会话/新建沙箱。排查密钥没生效时第一步就该确认这一点。4️⃣ 128 KB 合并上限只在多仓库场景触发单仓库很少超但多仓库会话把几个仓库的密钥叠在一起就容易爆。报错里的分作用域字节归因就是为它准备的——照着报错减对应作用域的值即可。5️⃣ 预构建镜像会把密钥烤进镜像镜像构建会执行你的.openinspect/setup.sh脚本里写入磁盘的内容.npmrc、.env、下载的凭证会被打进镜像之后每次启动都复用即使你已轮换密钥也不会更新。两条建议运行时从环境变量读取而非写盘环境密钥变更会自动使镜像失效重建但仓库/全局密钥轮换不会——所以尽量别把长效密钥留在镜像文件里。⚠️ 顺带一提OpenAI / xAI 的订阅制凭证不属于普通 Secrets应配置在Settings Provider Accounts其刷新令牌只留在控制平面永不注入沙箱。五、密钥不生效按这张自查清单走一遍✅ 密钥是否保存在正确作用域全局 / 对应仓库 / 对应环境✅ 键名是否撞上保留键清单含小写形式✅ 是否已重启会话让新密钥生效✅ 会话是从环境发起的吗是的话需把密钥加到环境或在环境 Secrets 页从仓库导入。✅ 模型报 Model not found核对模式所需密钥是否齐全Claude 用ANTHROPIC_API_KEYOpenAI 用OPENAI_API_KEYxAI 用XAI_API_KEY。六、延伸阅读与源码位置完整密钥管理文档作用域、安全模型、故障排查docs/SECRETS.md保留键与限制的后端校验实现secrets-validation.ts前端保存前的实时校验UI 报错来源secrets-editor.tsx快速上手含全局密钥配置步骤docs/GETTING_STARTED.md一句话总结避开 17 个保留键、记住单值 16KB / 单作用域 64KB / 单会话 128KB三层上限、保存后重启会话——background-agents 的密钥配置基本不会再坑到你。【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考