1. 从 trueforge 的执行循环倒推为什么第一步是 .env 而不是提示词在 trueforge 里跑 AI Agent真正的消耗发生在执行循环模型决定下一步、工具返回结果、再进模型、再调用工具。每转一圈都可能带着完整上下文去请求一次模型。如果 Key 散落在 shell、桌面客户端、CI 变量和临时脚本里第一次遇到 401 时你很难判断是容器没读到环境变量还是客户端把 base_url 写成了别的路径。所以从零搭建 trueforge 时我建议先把供应商层抽出来到 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_env_intro创建一个 Key然后把YOUR_API_KEY写进项目根目录的.envBase URL 固定为https://taotoken.net/api。这样 trueforge、Claude Code、Codex 以及后续的 CI 都可以复用同一套环境变量排障时只需要看一个入口。trueforge 本身不是替你写业务 Agent 的框架。它更像一个运行底座接管执行循环把模型调用、工具执行、沙箱隔离、人工审批这些脏活累活封装起来。你可以用聊天 UI 试玩也可以通过 API 或嵌入界面接到已有系统。它允许不绑定特定模型OpenAI 兼容接口和本地 vLLM 都能接所以用 TaoToken 作为统一模型入口是自然的做法。但要注意它不负责你的业务方向盘提示词、任务拆解、成功标准仍然要自己定义。另一个容易踩的坑是本地模式如果没有登录和鉴权不要直接把端口暴露到公网。接下来按从零搭建的顺序先建目录和 .env再启动 trueforge 本地模式然后验证模型调用链路最后把同一把 Key 配到 Claude Code、Codex 和 CC Switch 三件套里。2. 建目录与 .env 模板TaoToken Key 不写进代码从零开始先在本地准备一个干净目录。不要把 Key 写进main.py、docker-compose.yml或任何会提交到 Git 的文件。推荐结构trueforge-lab/ ├── .env ├── .env.example ├── .gitignore ├── compose.yaml └── data/.gitignore至少包含.env data/ *.log然后到 TaoToken 控制台创建 Key。访问 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_key_setup 登录后在 API Keys 页面生成。复制出来的 Key 只显示一次先放到.env的TAOTOKEN_API_KEY。这里用YOUR_API_KEY作为占位符你替换成真实值即可。.env.example可以写成下面这样方便团队复制# ---------- trueforge 本地运行 ---------- APP_ENVlocal BIND_HOST127.0.0.1 PORT8787 LOG_LEVELinfo # ---------- TaoToken 统一模型入口 ---------- TAOTOKEN_API_KEYYOUR_API_KEY TAOTOKEN_BASE_URLhttps://taotoken.net/api # ---------- trueforge 选择 OpenAI 兼容供应商 ---------- MODEL_PROVIDERopenai-compatible OPENAI_API_KEY${TAOTOKEN_API_KEY} OPENAI_BASE_URL${TAOTOKEN_BASE_URL} DEFAULT_MODELyour-model-id # ---------- 沙箱与审批 ---------- SANDBOX_ENABLEDtrue SANDBOX_NETWORKnone REQUIRE_APPROVALtrue # ---------- 本地模式安全 ---------- ALLOW_PUBLIC_BINDfalse说明几个关键点。第一TAOTOKEN_BASE_URL写https://taotoken.net/api不要在后面手滑加/v1。很多 OpenAI 兼容客户端会自动追加路径手动再加一层容易变成/api/v1/v1或/api/v1缺失。以你使用的 trueforge 版本和 SDK 行为为准但统一从https://taotoken.net/api开始排障。第二OPENAI_API_KEY和OPENAI_BASE_URL是给 trueforge 的 OpenAI 兼容适配层读的。不同版本可能叫LLM_API_KEY、MODEL_API_KEY、PROVIDER_BASE_URL但思路一样把 Key 和 Base URL 指向 TaoToken。不要改业务代码只改环境变量。第三DEFAULT_MODEL填什么以 TaoToken 控制台里可用的模型 ID 为准。如果你不确定可以先到模型对话页面测试文末有链接把界面上选择的模型 ID 复制到.env。第四本地模式务必BIND_HOST127.0.0.1并且把ALLOW_PUBLIC_BIND设成 false。原文提醒过本地模式没有登录直接暴露公网等于把执行循环交给陌生人。复制.env.example到.envcp .env.example .env # 用编辑器把 YOUR_API_KEY 替换成 TaoToken 控制台生成的 Key这样可复现产出之一就完成了.env模板。3. 启动 trueforge 本地模式命令、端口与健康检查trueforge 的部署方式有个人本地模式和团队托管模式。我们这里只搭本地模式目标是让执行循环跑起来并且只监听本机。下面给一个通用的 Docker Compose 启动方式。如果你的 trueforge 仓库提供的是 CLI 或 Node 脚本把command换成仓库 README 里的本地启动命令即可。compose.yaml示例services: trueforge: image: your-trueforge-image:latest container_name: trueforge-local env_file: - .env ports: - 127.0.0.1:8787:8787 volumes: - ./data:/app/data restart: unless-stopped注意ports写成127.0.0.1:8787:8787不要写8787:8787否则可能监听所有网卡。启动命令docker compose up -d docker compose logs -f trueforge如果你不用 Docker而是直接在仓库目录里跑典型流程是set -a source .env set a # 下面这条以 trueforge 仓库实际入口为准 # 例如 pnpm dev、npm run dev、python -m trueforge 或 ./scripts/dev.sh pnpm install pnpm devset -a和source .env的作用是把.env里的变量导出到当前 shell这样进程能读到TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL。如果你在 Docker 里env_file已经做了这件事不需要再手动 source。启动后做健康检查curl -s http://127.0.0.1:8787/health如果返回 JSON 且包含ok或healthy说明服务起来了。然后打开本地聊天 UI或者调用它的 API发一条最简单的消息。trueforge 会开始执行循环把消息发给模型如果模型要求调用工具它会在沙箱里执行再把结果回传。每一次循环都会消耗 Token所以建议一开始就用一个短提示词测试比如“只回复 OK”不要一上来就扔长任务。如果启动失败先看日志里有没有401 Unauthorized、invalid api key、connection refused。401 通常是.env没被读到或者 Key 复制时带了空格。connection refused则要检查BIND_HOST和端口映射。4. 模型调用链路验证让 trueforge 的循环真正打到 TaoToken服务起来不等于模型通了。我们需要单独验证https://taotoken.net/api是否能从当前环境访问以及 Key 是否有效。可以用一段最小 Python 脚本不依赖 trueforge先验证 OpenAI 兼容链路import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) resp client.chat.completions.create( modelos.environ[DEFAULT_MODEL], messages[ {role: user, content: 只回复四个字链路正常} ], temperature0, ) print(resp.choices[0].message.content)运行前确保已经导出.envset -a source .env set a python check_taotoken.py如果这段脚本能打印出预期内容说明 Key、Base URL、模型 ID 三件事至少是对的。接下来回到 trueforge在聊天 UI 或 API 里发一个需要调用工具的任务比如“先读取当前目录下的 README 前 20 行然后总结成一句话”。观察日志里是否出现模型请求和工具调用。trueforge 会接管执行循环你不需要自己写while True去轮询模型。这里要建立 Token 消耗意识。执行循环越多模型请求越多Token 消耗越快。把 Key 放在.env的好处是你可以在 TaoToken 控制台按 Key 维度看用量也可以在本地日志里记录每次请求的模型和 Token 数。不要等到账单异常才发现某个 Agent 在死循环里空转。给循环加步数上限、超时和人工检查点是 trueforge 这类底座值得用的原因。5. 同一把 TaoToken Key 配 Claude Code、Codex 与 CC Switch 三件套trueforge 跑起来之后你通常还会在终端里用 Claude Code、Codex 或其他编码助手。与其每个工具申请一套 Key不如让它们都指向 TaoToken 的https://taotoken.net/api。但要注意Claude Code 和 Codex 的配置格式完全不同不要把 Anthropic 的环境变量套到 Codex 上。先看 Claude Code。它读settings.json里的env块常用变量是ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。示例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: your-claude-model-id } }把这段放到 Claude Code 的settings.json。如果你使用 CC Switch 管理多套配置可以把不同供应商写成不同 profile但 Key 仍然建议从环境变量或统一的.env来避免在多个 JSON 里重复硬编码。再看 Codex。Codex 使用config.toml供应商配置走model_providers不要在这里写ANTHROPIC_*。示例model your-model-id model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY这段配置的意思是Codex 从环境变量TAOTOKEN_API_KEY读取 Key把请求发到https://taotoken.net/api。你可以在.env或 shell profile 里导出TAOTOKEN_API_KEYYOUR_API_KEY。如果你同时在用 trueforge这个变量已经存在直接复用即可。所谓 CC Switch 三件套可以理解为三处配置各司其职Claude Code 的settings.json管 Anthropic 兼容端点和模型Codex 的config.toml管 OpenAI 兼容供应商和模型项目或全局的.env管TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL这类共享变量。不要混用Claude Code 的ANTHROPIC_AUTH_TOKEN不要写到 Codex 的config.tomlCodex 的env_key也不要指望 Claude Code 自动读取。CC Switch 的价值在于切换配置而不是替你消除格式差异。6. 常见报错与排障401、404、429、流式中断、沙箱权限从零搭环境最耗时间的不是写业务逻辑而是排障。下面按报错类型整理。6.1 401 Unauthorized / invalid api key优先检查.env是否真的被进程读到。Docker 里看docker compose config是否包含TAOTOKEN_API_KEY本地脚本里用env | grep TAOTOKEN确认。常见原因Key 占位符YOUR_API_KEY没替换复制时带了换行或空格变量名不一致比如 trueforge 读的是OPENAI_API_KEY你只写了TAOTOKEN_API_KEY。解决方式是让OPENAI_API_KEY${TAOTOKEN_API_KEY}。6.2 404 Not Found / model not foundBase URL 或模型 ID 不对。TaoToken 的 Base URL 用https://taotoken.net/api。如果客户端自动追加/v1最终路径可能是https://taotoken.net/api/v1/chat/completions具体以客户端行为为准。不要手写https://taotoken.net/api/v1/v1。模型 ID 则要去控制台或模型对话页面确认不要凭记忆写gpt-4或claude-3这类模糊名称。6.3 429 Too Many Requests执行循环并发一高瞬间就会打出很多请求。trueforge 如果有多个工具并行或者你本地同时跑 Claude Code 和 Codex触发限流很正常。处理方式降低并发给工具调用加队列对模型请求加指数退避在.env里设置最大步数避免 Agent 空转把非关键任务换成更小模型。6.4 流式输出中断流式输出对网络稳定性更敏感。如果 trueforge 的聊天 UI 流到一半断了先看日志是客户端超时还是服务端超时。检查反向代理的 read timeout、容器网络、以及沙箱网络策略。本地模式下SANDBOX_NETWORKnone是安全选择但如果你允许沙箱访问网络要确保它不会绕过你的出口限制。6.5 沙箱权限与公网暴露trueforge 的卖点之一是沙箱即工具代码在隔离环境跑。但沙箱不是魔法权限仍然要配。关键操作加审批能防误删。本地模式没登录不要把BIND_HOST改成0.0.0.0后直接映射到公网。需要团队访问时用托管模式或加一层鉴权网关。更多部署细节可以在 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_troubleshoot 的控制台文档里对照查看。7. 生产化前的检查清单与下一步当你已经能用 trueforge 跑通一个最小 Agent下一步不是马上接生产库而是先做以下检查Key 是否只在.env或密钥管理服务里Git 历史是否干净BIND_HOST是否限制在127.0.0.1公网入口是否有鉴权沙箱是否默认禁网允许联网时是否白名单关键工具调用是否开启人工审批执行循环是否有最大步数、超时和 Token 预算日志是否记录模型、耗时、Token 用量和错误码本地命令和 SQL 是否只在可信环境执行不要让 Agent 直接连生产数据库。完成这些之后你就可以把 trueforge 当作 Agent 运行底座把精力放回业务逻辑。模型供应商层继续用 TaoToken 统一管理换模型时只改.env里的DEFAULT_MODEL或客户端配置不用改业务代码。如果你还没有 Key可以先到 TaoToken 控制台创建然后按本文的.env模板接入先试模型对话https://taotoken.net/models/detail/chat?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_chat需要长期高频调用看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_coding_plan创建和管理 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_api_keysClaude Code 接入文档https://taotoken.net/doc/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contenttrueforge_claude_code先把.env写对再启动 trueforge最后用一段最小循环验证 Token 消耗。环境稳了Agent 才谈得上跑得稳。