1. Refly 部署卡在 .env模型通道没打通后面全是空转Refly 是一个开源的 AI Agent 技能构建平台核心卖点是「Skills are infrastructure, not prompts」——把搜索、分析、生成、修改这些环节串成可观测、可干预、可复用的工作流。它自带 Vibe Workflow 可视化编排、确定性运行时、Refly Canvas 多线程画布还原生支持 MCP 协议去调第三方工具。适合谁有后端基础、想快速搭 Agent 原型的开发者以及需要把 AI 能力工程化的内容创作者。但很多人第一次部署就卡住了git clone完进deploy/dockercp env.example .env然后对着那一行模型配置发呆。填 OpenAI 的 Key网络不通。填 Claude 的格式又对不上。更隐蔽的是——就算你随便填了个 Keydocker compose up -d也能起来http://localhost:5700也能打开可一旦建第一个 Skill 跑起来Vibe Workflow 转圈、MCP 工具调用超时、Canvas 多线程对话直接报模型不可用。问题的本质是Refly 只是技能与工作流的运行时真正消耗 Token 的是它背后调用的模型通道。模型配置没通整个平台就是个空壳。这篇就按「排障」视角把env.example里那段模型配置当成排查对象一步步改到能跑通最小 Skill。2. 先拿到可用的 Key 与 Base URLRefly 的.env里需要两样东西一个 API Key一个模型服务的 Base URL。我试过直接填某些海外服务的地址容器里请求经常超时排查半天发现是网络链路的问题。后来换成 TaoToken 的通道配置就干净很多。打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册账号进控制台创建一把 API Key。地址是 https://taotoken.net/api-keys 创建后复制那串sk-开头的 Key先存到记事本里。这里有个关键点Base URL 填https://taotoken.net/api不要带/v1也不要填带 utm 参数的官网地址。很多人习惯性写成https://taotoken.net/api/v1结果 Refly 内部再拼一次路径就变成/v1/v1/chat/completions直接 404。官网地址是给人看的API 地址才是给程序调的这两个别混。TaoToken 在这里只提供 Key 与 Base URL不替代 Refly 的工作流编排、画布或确定性运行时。Refly 负责「怎么串技能」TaoToken 负责「模型从哪来」分工清晰。3. 改 .env把模型配置逐行对齐进到 Refly 的部署目录先确认你在正确的位置cd refly/deploy/docker ls -la你应该能看到env.example、docker-compose.yml这些文件。复制一份环境变量模板cp env.example .env然后用编辑器打开.env找到模型相关的段落。不同版本的 Refly 变量名可能略有差异但核心就三类Base URL、API Key、模型名。下面是我实测下来能跑通的配置写法你可以对照自己的env.example调整# 模型通道配置 # Base URL 不带 /v1不要填官网地址 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_API_KEYsk-你刚创建的那把Key # 默认模型名按你实际要用的填 OPENAI_MODELgpt-4o-mini # 如果 Refly 版本区分了 providerClaude 系也走同一通道 ANTHROPIC_BASE_URLhttps://taotoken.net/api ANTHROPIC_API_KEYsk-你刚创建的那把Key ANTHROPIC_MODELclaude-3-5-sonnet-20241022几个容易踩的坑我列成表格对照配置项错误写法正确写法后果Base URLhttps://taotoken.net/api/v1https://taotoken.net/api路径重复404Base URLhttps://taotoken.net/?utm_source...https://taotoken.net/api带查询参数请求异常API Key引号包裹sk-xxx裸写sk-xxx部分解析器把引号当值模型名留空填具体模型运行时不知道调哪个注意.env文件不要提交到 Git里面是明文 Key。Refly 的.gitignore通常已经忽略了它但你自己确认一下。改完保存别急着启动。先做一次语法自检grep -E BASE_URL|API_KEY|MODEL .env确认输出的 Base URL 是https://taotoken.net/api没有多余的/v1或 utm 尾巴。4. 重启容器并跑通最小 Skill 验证配置改完必须重新拉起容器因为.env是在容器启动时注入的docker compose down docker compose up -d等十几秒看容器状态docker compose ps所有服务显示running或healthy后打开http://localhost:5700。登录进控制台新建一个最简单的 Skill——就一个「输入问题返回模型回答」的单步流程不要加 MCP 工具、不要加多线程分支先把模型通道验证通。在 Skill 的模型节点里确认它读取的是你.env里配的通道。保存后点运行输入一句「你好请回复 OK」。如果几秒内返回了内容说明模型通道打通了。这时候你再去试 Vibe Workflow 的多步串联、Canvas 的多线程对话才有意义。如果返回报错先看容器日志docker compose logs -f --tail100日志里通常会打印实际请求的 URL 和状态码。看到401就是 Key 不对看到404就是 Base URL 路径拼错了看到timeout就是网络链路问题。对着日志改.env再docker compose restart对应服务即可不用整个 down 掉。5. 本篇常见错排查清单排障时按这个顺序走能省不少时间。第一确认.env真的被容器读到了——有时候你在根目录改了.env但docker-compose.yml里指定的env_file路径是deploy/docker/.env两个文件不是一个。用docker compose config可以打印出最终生效的环境变量搜一下BASE_URL看值对不对。第二Key 的权限和额度。刚创建的 Key 如果没绑定任何模型权限请求会返回 403。进控制台确认这把 Key 可用、余额充足。第三模型名拼写。gpt-4o-mini和gpt-4o是两个模型写错了会报 model not found。Claude 系同理日期后缀别漏。第四容器内 DNS。如果日志显示域名解析失败进容器里curl一下docker compose exec 服务名 curl -I https://taotoken.net/api能返回 HTTP 状态码就说明网络通返回不了就是容器网络配置问题检查docker-compose.yml里的network_mode和 DNS 设置。第五改完.env忘了重启。环境变量不会热加载必须docker compose up -d重建容器才生效。这个坑我踩过不止一次。6. 通道通了之后Refly 才真正开始工作模型通道打通后Refly 的确定性运行时、MCP 第三方工具调用、Canvas 多线程对话才有可用的模型支撑。你可以回到控制台把刚才那个最小 Skill 逐步加上搜索节点、分析节点观察每一步的输入输出——这就是 Refly 区别于黑盒 Prompt 平台的地方执行过程可观测、可干预。如果你后面要长期跑编码类 Agent或者把 Refly 的技能接到 Claude Code、Cursor 里可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。想直接在网页里验证模型返回是否正常用模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后留一个实用习惯每次改完.env先docker compose config | grep BASE_URL确认生效值再启动。这一步花十秒能省掉后面半小时的日志排查。