1. 从 401 到容器重启丢 Keytrueforge 认证链的故障面把 trueforge 跑起来时最容易被忽略的不是 agent loop而是认证。你npx truefoundry/trueforgelatest起服务聊天 UI 能打开但模型调用报401 invalid api key或者本地跑通了一做成 Docker 服务重启后 Key 没了又或者 MCP 工具能连但沙箱执行器读不到模型凭据。这些现象背后通常是同一个问题模型认证、工具认证、运行时凭据被塞在一个.env里没有分层。从应用安全工程师视角第一步是把 TaoToken 作为模型供应商接进来。先访问 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_env_intro创建账号并获取 API Key。注意Key 生成后只显示一次别顺手粘进docker-compose.yml或前端配置文件。然后把 Base URL 固定为https://taotoken.net/api这个地址只用于服务端工具配置不加 UTM 参数。模型请求由 trueforge 的 agent loop 发起Token 也由认证后的 agent 模型调用消耗所以 Key 的权限范围要按“模型调用”而不是“全账号”来设计。这一节先给结论trueforge 的认证管理不要硬写。你需要三样东西——环境变量模板、认证配置片段、Key 轮换检查表。下面按可复现顺序展开。2. 最小可用环境变量模板TaoToken Key 不进代码库先做环境变量。建议把模型认证与工具认证拆成两组变量即使第一版只有一个 Key也不要混名。你可以先到 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_env_key生成一个专用 Key再回到服务端写入.env。# .env.example # 模型认证trueforge 调用大模型时使用 TAOTOKEN_API_KEYYOUR_API_KEY TAOTOKEN_BASE_URLhttps://taotoken.net/api # 运行时隔离给 trueforge 容器/进程读取 TRUEFORGE_MODEL_PROVIDERopenai-compatible TRUEFORGE_MODEL_NAMEyour-model-name # 工具认证MCP server 或内部检索工具使用独立 Key MCP_INTERNAL_SEARCH_TOKENYOUR_MCP_TOKEN # 审计与日志不要记录完整 Key LOG_LEVELinfo LOG_REDACT_KEYStrue真正的.env不要提交cp .env.example .env chmod 600 .env printf .env\n.env.*\n*.pem\n .gitignore如果 trueforge 用 Docker Compose 启动让容器通过env_file读取而不是在command里写services: trueforge: image: your-trueforge-image env_file: - .env environment: - TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} - TAOTOKEN_BASE_URL${TAOTOKEN_BASE_URL} read_only: true user: 10001:10001 security_opt: - no-new-privileges:true这里的关键不是 Compose 语法而是边界TAOTOKEN_API_KEY只进入模型调用进程MCP_INTERNAL_SEARCH_TOKEN只进入工具进程日志层做脱敏。很多“Key 泄露”不是被黑客拖库而是调试日志把Authorization: Bearer打进了 stdout。如果你在服务器上手动验证可以本地执行set -a source .env set a curl -sS https://taotoken.net/api/models \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -o /tmp/models.json这个命令只用于确认认证链通不通不要把它放进 agent 可调用的工具列表。工具一旦能执行任意 curlKey 就可能被带出去。3. 模型认证片段OpenAI-compatible provider 如何指向 TaoToken APItrueforge 支持任意模型提供商包括兼容 OpenAI 的端点。接入 TaoToken 时核心是让模型 provider 从环境变量读取两个值TAOTOKEN_BASE_URL和TAOTOKEN_API_KEY。不同版本的 trueforge 配置文件字段可能不同下面给的是通用结构。你需要到实际配置文件里把字段名对齐但原则不变YAML/JSON 里只留变量名不留明文 Key。# 示例模型 provider 片段字段名以你安装的 trueforge 版本为准 model: provider: openai-compatible name: taotoken base_url: ${TAOTOKEN_BASE_URL} api_key: ${TAOTOKEN_API_KEY} model: ${TRUEFORGE_MODEL_NAME} timeout_ms: 60000 max_retries: 2如果 trueforge 的某部分只接受运行时注入而不是 YAML 插值就在启动脚本里做映射#!/usr/bin/env bash set -euo pipefail : ${TAOTOKEN_API_KEY:?missing TAOTOKEN_API_KEY} : ${TAOTOKEN_BASE_URL:?missing TAOTOKEN_BASE_URL} export OPENAI_BASE_URL${TAOTOKEN_BASE_URL} export OPENAI_API_KEY${TAOTOKEN_API_KEY} exec npx truefoundry/trueforgelatest注意这里只是把 TaoToken 的 Key 映射给兼容 OpenAI 的 provider。不要因为 trueforge 支持 Anthropic、Gemini 就同时把ANTHROPIC_API_KEY、GEMINI_API_KEY全塞进去。多供应商并存时每个 provider 单独命名变量例如TAOTOKEN_API_KEYYOUR_API_KEY TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELyour-model-name在应用安全层面推荐给模型 Key 单独建一个“环境级”凭证而不是复用个人控制台 Key。这样当 agent 被 prompt injection 诱导去发请求时损失范围只限于模型调用额度不会牵出控制台权限。如果你要在 TypeScript 代码里检查配置是否完整可以写一个启动前校验而不是等到请求失败function assertModelEnv() { const required [TAOTOKEN_API_KEY, TAOTOKEN_BASE_URL]; for (const key of required) { if (!process.env[key]) { throw new Error(Missing required env: ${key}); } } if (!process.env.TAOTOKEN_BASE_URL!.startsWith(https://)) { throw new Error(TAOTOKEN_BASE_URL must be https); } } assertModelEnv();这段代码不调用模型只做配置门禁。它的价值是让错误在启动阶段暴露而不是在用户提问时才出现401。4. 工具认证与模型认证分离MCP、沙箱、审批各自的凭据边界trueforge 把 MCP 工具、技能、沙箱、审批、上下文管理都接管了。对认证管理来说这不是“少写代码”而是“多了一条安全边界”。模型认证解决的是“谁可以调用大模型”工具认证解决的是“这个 agent 可以代表谁去访问哪个工具”。两者不能用同一个 Key。原因很直接模型 Key 泄露后攻击者至少可以消耗额度、探测模型工具 Key 泄露后攻击者可能读写内部文档、触发代码执行、甚至访问业务系统。把两者分开才能做最小权限和独立轮换。一个工具侧的环境变量模板# MCP 内部检索工具只读凭据 MCP_SEARCH_BASE_URLhttps://internal.example.com/search MCP_SEARCH_TOKENYOUR_MCP_TOKEN MCP_SEARCH_SCOPEdocs:read # 沙箱执行器不要挂载宿主机敏感目录 SANDBOX_IMAGEyour-sandbox-image SANDBOX_TIMEOUT_SECONDS30 SANDBOX_NETWORKnone # 审批回调独立签名密钥 APPROVAL_CALLBACK_SECRETYOUR_CALLBACK_SECRET在 trueforge 的工具配置里MCP server 的凭据应该由运行时注入而不是写在SKILL.md或前端可读的配置里。若你的 MCP server 需要访问数据库请只给它只读账号并明确禁止 agent 直连生产库。SQL 和运维命令由读者在本地或受控终端执行agent 只拿结果不拿写权限。一个常见的错误配置是为了让 agent “更方便”把数据库连接串直接塞进 MCP server 的env然后让 agent 生成 SQL 并执行。这样做等于把生产库的写权限交给了一个可能被 prompt injection 影响的执行循环。正确做法是分三层agent 只调用一个“查询建议”工具输出 SQL 文本审批流由人工在受控界面确认实际 SQL 由读者本地或专用只读执行器执行结果再回灌给 agent。trueforge 的人工检查点正好可以用在这里。把“执行 SQL”这个动作设为需要审批审批通过后也只调用只读账号。工具认证的 scope 要写成read不要为了省事写admin。5. Claude Code、Codex、CC Switch 三件套的配置差异很多团队同时在用 trueforge、Claude Code、Codex还有 CC Switch 做配置切换。这里最容易踩的坑是变量名串台把ANTHROPIC_*套到 Codex 上或者把 Codex 的config.toml当成 Claude Code 的 settings.json 改。下面分开写。Claude Code 用settings.json和ANTHROPIC_*系列变量。典型配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: your-model-name } }这里ANTHROPIC_AUTH_TOKEN放的是 TaoToken 控制台生成的 Key 占位符。不要把ANTHROPIC_BASE_URL写成带 UTM 的官网地址UTM 只用于文档链接Base URL 保持https://taotoken.net/api。Codex 用config.toml不要写ANTHROPIC_*。示例model your-model-name model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY然后在 shell 或密钥管理里导出export TAOTOKEN_API_KEYYOUR_API_KEYCC Switch 三件套通常指全局配置、项目级配置、凭据引用这三类文件。无论你用哪一版 CC Switch原则都是三件套里只放环境变量名和 base URL不放明文 Key。建议做一张对照表工具主配置认证变量Base URLClaude Codesettings.jsonANTHROPIC_AUTH_TOKENhttps://taotoken.net/apiCodexconfig.tomlTAOTOKEN_API_KEYhttps://taotoken.net/apitrueforge模型 provider 配置TAOTOKEN_API_KEYhttps://taotoken.net/apiCC Switch三件套中的 env 引用指向系统环境变量不重复写 Key这样切换工具时只改配置引用不复制 Key。应用安全工程师要特别检查不要为了让 Codex 跑起来把 Claude Code 的ANTHROPIC_AUTH_TOKEN改名为OPENAI_API_KEY就塞进去。变量名不对应出错时日志会误导排查方向。6. Key 轮换检查表从创建到撤销的 9 个动作Key 轮换不是“过 90 天换一次”这么简单。对 agent 系统轮换要兼顾会话连续性和审计可追溯性。下面是一张可以直接贴到 runbook 的检查表。阶段动作判定标准1. 创建在 TaoToken 控制台创建新 Key命名带环境和用途如prod-trueforge-model-2026q3不与其他环境共用2. 登记记录 Key ID、创建人、用途、关联服务不记录完整 Key 明文3. 注入通过 secrets manager / 环境变量注入不写入代码库git grep无明文4. 灰度先切一个非关键 agent 实例观察 401、429、延迟错误率不高于基线5. 全量批量更新 trueforge 实例并滚动重启无会话状态丢失6. 观察观察 24 小时检查模型调用日志和工具调用日志无异常来源7. 撤销在控制台禁用旧 Key旧 Key 请求全部 4018. 审计检查旧 Key 在禁用前是否有未知调用无异常 IP、无越权工具9. 复盘更新轮换记录必要时缩短周期周期与风险匹配轮换时特别容易忽略两点。第一trueforge 的本地模式可能用 SQLite 存会话如果你直接删容器会话状态会丢。轮换 Key 之前先确认会话存储位置和备份策略。第二MCP 工具 Key 和模型 Key 的轮换节奏可以不同但必须在同一张表里登记。否则半年后没人知道哪个 Key 对应哪个工具。如果你使用托管模式Postgres Redis 的环境里建议把 Key 轮换和 OIDC 登录分开OIDC 管“谁在使用 trueforge”TaoToken Key 管“trueforge 用什么调用模型”。两者混淆会导致权限模型失控。7. 生产边界与审计本地模式、托管模式、日志脱敏trueforge 的本地模式是一条命令起的单进程默认没有登录数据落在本地文件。官方定位是试用不是生产配置应该留在 localhost。如果你要把聊天 UI 共享给同事或者让 agent 接内部知识库请切到托管模式Postgres Redis OIDC 登录。认证管理也要同步升级。从应用安全视角至少做四件事第一环境变量不是保险箱。容器里/proc/1/environ可能被同主机进程读取所以生产环境优先用 secrets manager 或编排平台的原生 secret。环境变量模板是第一层不是唯一一层。第二日志脱敏。trueforge 会记录模型调用和工具调用。你需要确保Authorization、api_key、token字段被打码。可以在日志管道里加过滤规则# 示例本地日志脱敏检查 grep -R Bearer \|api_key\|TAOTOKEN_API_KEY ./logs \ | sed -E s/(Bearer )[A-Za-z0-9._-]/\1***/g \ | head -n 20第三最小网络出口。模型请求只允许访问https://taotoken.net/api工具请求只允许访问内部工具域名。不要给 agent 容器开放全量出网否则 Key 泄露后的外传路径会很多。第四审批与审计分离。关键操作前的审批记录、工具调用记录、模型调用记录要能关联到同一个会话 ID。这样出现异常时你能回答三个问题谁触发的、调用了哪个模型、动了哪个工具。8. 一次完整接入核对从模型对话到 Claude Code 文档最后给一条核对路径。先到 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_env_checklist确认账号和 Key 状态然后按顺序做四步打开模型对话验证 Key 能正常调用模型查看 Coding Plan确认 agent 场景的用量和权限边界到 API Keys 页面创建或轮换专用 Key对照 Claude Code 文档把配置写进对应工具。四个深链如下按你的实际工具选择模型对话https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_env_chatCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_env_plan创建 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_env_keysClaude Code 文档https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_env_cc核对清单可以压缩成一段[ ] .env 已加入 .gitignore权限 600 [ ] TAOTOKEN_API_KEY 只存在于模型进程 [ ] TAOTOKEN_BASE_URLhttps://taotoken.net/api不带 UTM [ ] MCP 工具使用独立 Keyscope 最小化 [ ] agent 不直连生产库SQL 由本地/只读执行器执行 [ ] Claude Code 使用 settings.json ANTHROPIC_* [ ] Codex 使用 config.toml不使用 ANTHROPIC_* [ ] CC Switch 三件套不存明文 Key [ ] Key 轮换表已登记 Key ID、用途、负责人 [ ] 日志已脱敏模型调用与工具调用可审计trueforge 解决的是让 agent“跑起来、跑稳、跑安全”的脏活而认证管理是其中最容易在演示阶段被跳过、在生产阶段爆发的一环。把 TaoToken Key 放进环境变量只是起点真正的终点是每个 agent、每个工具、每次调用都有清晰的凭据边界Key 可以轮换日志可以审计故障可以定位。做到这些你才敢让 agent 离开 localhost。