企业官网建设流程全解析

1. Refly 部署卡在 .env：模型通道没打通，后面全是空转

Refly 是一个开源的 AI Agent 技能构建平台，核心卖点是「Skills are infrastructure, not prompts」——把搜索、分析、生成、修改这些环节串成可观测、可干预、可复用的工作流。它自带 Vibe Workflow 可视化编排、确定性运行时、Refly Canvas 多线程画布，还原生支持 MCP 协议去调第三方工具。适合谁？有后端基础、想快速搭 Agent 原型的开发者，以及需要把 AI 能力工程化的内容创作者。

但很多人第一次部署就卡住了：git clone完，进deploy/docker，cp env.example .env，然后对着那一行模型配置发呆。填 OpenAI 的 Key？网络不通。填 Claude 的？格式又对不上。更隐蔽的是——就算你随便填了个 Key，docker compose up -d也能起来，http://localhost:5700也能打开，可一旦建第一个 Skill 跑起来，Vibe Workflow 转圈、MCP 工具调用超时、Canvas 多线程对话直接报模型不可用。

问题的本质是：Refly 只是技能与工作流的运行时，真正消耗 Token 的是它背后调用的模型通道。模型配置没通，整个平台就是个空壳。这篇就按「排障」视角，把env.example里那段模型配置当成排查对象，一步步改到能跑通最小 Skill。

2. 先拿到可用的 Key 与 Base URL

Refly 的.env里需要两样东西：一个 API Key，一个模型服务的 Base URL。我试过直接填某些海外服务的地址，容器里请求经常超时，排查半天发现是网络链路的问题。后来换成 TaoToken 的通道，配置就干净很多。

打开 https://taotoken.net/?utm_source=taotoken_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_URL=https://taotoken.net/api OPENAI_API_KEY=sk-你刚创建的那把Key # 默认模型名，按你实际要用的填 OPENAI_MODEL=gpt-4o-mini # 如果 Refly 版本区分了 provider，Claude 系也走同一通道 ANTHROPIC_BASE_URL=https://taotoken.net/api ANTHROPIC_API_KEY=sk-你刚创建的那把Key ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

几个容易踩的坑，我列成表格对照：

注意：.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 --tail=100

日志里通常会打印实际请求的 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 Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。想直接在网页里验证模型返回是否正常，用模型对话：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。

最后留一个实用习惯：每次改完.env，先docker compose config | grep BASE_URL确认生效值，再启动。这一步花十秒，能省掉后面半小时的日志排查。