Vibe-Trading 开源交易 Agent：三个入口与第一次配置
本文基于 Vibe-Trading 仓库 commit 3a752d5（2026-08-04）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/HKUDS/Vibe-Trading 最新代码与文档为准。
装 Vibe-Trading 这件事本身没有难度，真正需要你做决定的是：你打算把它放在哪条信任边界的哪一侧。 同一份代码，跑成本机交互命令行、跑成监听端口的 Web 服务、跑成别人 agent 的 MCP 子进程，暴露面完全不同——仓库里对这三种形态给的默认权限也确实不一样。第一次配置向导只问你五个问题，但它写下的那个文件决定了后面所有工具能碰到什么。
先说清楚命名：Vibe-Trading 是 HKUDS 这个组织放出的开源项目的项目名（许可证 MIT，Copyright 2026 Vibe-Trading Contributors），不是「凭感觉交易」这类泛指说法。下文出现这个词时一律指这个仓库。
这篇只谈工程：装、配、跑通第一次调用。站内另有三篇和它挨着但不重叠——Claude Code 装不上时的排查路径讲的是单个工具装不上的故障树，AI 工具选型流程讲的是「要不要引入」这一步的判断方法，MCP server 本地怎么测讲的是通用的 MCP 联调手法；本篇只负责 Vibe-Trading 这一个仓库从零到第一次跑通的那一段。
一、三个入口对应三条信任边界
pip install vibe-trading-ai 之后，仓库文档里明确列出的可执行命令是三个：vibe-trading（交互式 CLI / TUI）、vibe-trading serve（启动 FastAPI Web 服务）、vibe-trading-mcp（以 stdio 启动 MCP 服务端）。注意包名和命令名不一致，PyPI 上的包叫 vibe-trading-ai，装完给你的命令没有 -ai 后缀。
这三个入口不是同一件事的三种皮肤。差别在权限：
交互 CLI 是权限最宽的那个。README 的安全默认值一节写得很直白——具备 shell 能力的进程类工具（bash / background_run / cancel_background）只在本机交互式 CLI 里启用。它假设坐在终端前的人就是操作者本人。
vibe-trading serve 默认绑 0.0.0.0，但只对回环地址放行。同一台机器上开 http://localhost:8899 零配置可用；从另一台机器、虚拟机宿主或手机上访问，敏感端点直接返 403，聊天界面会提示远程访问需要 API key。要跨机访问就得设 API_AUTH_KEY，重启，然后在 Settings 里输一次同样的 key。Docker 路径默认把后端发布在 127.0.0.1:8899 并以非 root 容器用户运行，方向是一致的。
vibe-trading-mcp 是给别的 agent 当工具箱用的。它跑成客户端拉起的 stdio 子进程，没有服务端要管。这条路径上有两个容易被忽略的约束：一是 shell 类工具在所有 transport（含 stdio）上默认关闭，除非你显式给 --enable-shell-tools 或设 VIBE_TRADING_ENABLE_SHELL_TOOLS=1——README 的原话是「传输类型本身永远不隐式授予 shell 权限」；二是下单类工具结构上就不上 MCP，只在 agent 和 CLI 里存在。
顺带一个可核的小出入：agent/SKILL.md 的工具表标题写的是 55 个 MCP 工具，README 的 MCP Plugin 段落开头一句写的是 54 个，同一份 README 往下那份逐个列名的清单标题又写回 55。仓库自己这三处口径就没对齐，别把这个数字当硬事实用，要精确数就自己接上客户端跑一次 tools/list。
怎么选？如果只是想在自己机器上问几个问题、跑几段回测，CLI 最省事；想要图表、会话历史、定时任务这些界面能力就上 serve；如果你已经有一个日常在用的 agent（Claude Desktop、Cursor 之类），MCP 是把这套工具嫁接进去而不用换主场的做法。
二、第一次配置：五步向导要你交出什么
agent/cli/onboard.py 的模块 docstring 把触发条件写死了：当 ~/.vibe-trading/.env 不存在时自动触发首次启动向导。你也可以随时用 vibe-trading init 手动再跑一遍——agent/cli/main.py 里那个 typer 命令的 help 就是「重跑交互式设置向导」。
五步的顺序是 provider → model → key → timeout → 可选的 Tushare。每一步都可回退：向上/向下箭头导航，回车确认，Esc 或左箭头回上一步，Ctrl+C 取消。在第一步按 Esc，向导会直接退出并明确告诉你「没有写任何配置」。
落盘方式值得单独说一句，这是个抄得走的工程细节。每一步完成后立刻写入 ~/.vibe-trading/.env.partial，只有全部走完才通过临时文件加原子 rename 写成最终的 .env，然后删掉 partial。代码注释里写明了理由：向导中途崩溃永远不会留下一个残缺的 .env。写文件时还会尽力 chmod 0o600，失败时静默吞掉 OSError（Windows 上就是这个分支）。
各步骤具体写进 .env 的键：
- 第一步选 provider，写
LANGCHAIN_PROVIDER和该 provider 对应的 base URL 变量。PROVIDERS这个元组里内置的选项有 openrouter、requesty、openai、anthropic、openai-codex、deepseek、siliconflow-cn、siliconflow-global、nvidia、ollama 十项，每项带默认模型和几个建议模型。 - 第二步选模型，写
LANGCHAIN_MODEL_NAME。列表里最后一项是「other」，可以手打自定义模型 id。 - 第三步要 API key，输入是掩码的，提示语里写着「保存到
~/.vibe-trading/.env，永不记录日志」。_validate_key会当场校验三件事：非空、前缀匹配、长度不小于 12。前缀是 provider 自带的字段，比如 OpenRouter 要求sk-or-开头，NVIDIA NIM 要求nvapi-。校验不过会让你重输或按 Esc 回退。 - 第四步选默认请求超时，写
TIMEOUT_SECONDS，三个选项分别标注为研究模式、大型回测/swarm 运行、快速查询模式。 - 第五步问要不要启用 Tushare 取 A 股数据，默认选项就是「不，跳过（大多数用户）」。
另外向导在开始时就把 LANGCHAIN_TEMPERATURE=0.0 和 MAX_RETRIES=2 预置进了待写值里，不问你。
想看全部可调项就去读 agent/.env.example，那份文件第一行直接告诉你所有默认值定义在 agent/src/config/env_schema.py 的 EnvConfig 里。
三、哪些东西其实可以先不给
这是本篇最想说清楚的一节。第一次跑通一次研究，你不需要交出的东西比想象中多。
行情数据密钥可以先不给。 agent/SKILL.md 里这样描述：港股/美股/加密货币走 yfinance / stooq / yahoo 加 OKX，全程免密钥；A 股走 akshare / baostock / tencent / sina / eastmoney / mootdx 的回退链，也不需要 token，TUSHARE_TOKEN 只是可选的品质升级项。所以向导第五步默认跳过是合理的默认。
LLM 密钥不是全都要。 向导里 openai-codex 和 ollama 两项的 key_env 字段是 None，走到第三步会直接跳过：Ollama 本地跑不需要 key；OpenAI Codex 走 ChatGPT OAuth，向导会提示你配置完之后执行 vibe-trading provider login openai-codex。
券商凭据一开始完全不用碰。 这是最重要的一条。回测、行情、因子、期权定价、文档解析这些研究路径和实盘路径在仓库里是分开的，README 明确写「研究/回测路径在结构上被禁止访问任何实盘端点」。你可以把整套东西跑到很深都不接任何券商。
外部 MCP 服务器也是可选的。 仓库支持反向的一条路：让 Vibe-Trading 自己的 agent 去调你的 MCP server，配置写在 ~/.vibe-trading/agent.json 的 mcpServers 里，加载进来的工具以 mcp_<server>_<tool> 的稳定命名注入。这条路的 v1 限制写得很清楚：传输支持 stdio / SSE / streamable HTTP；执行只有串行，MCP 工具不进并行只读路径；只暴露 tools，不暴露 resources 和 prompts；swarm worker 的注册表里排除 MCP 工具；不支持热重载，改配置要重启进程。最后这条要多留个心眼：README 另有一节写 swarm worker 可以调用「经运营者批准」的外部 MCP 工具，白名单配在 VIBE_TRADING_SWARM_AGENT_CONFIG、~/.vibe-trading/swarm-agent.json 或退回 agent.json，VIBE_TRADING_SWARM_AGENT_CONFIG 和这个退回链在 agent/src/config/loader.py 里都能查到。也就是说「swarm 排除 MCP」这条限制和后来加的白名单机制在文档里并存，真要用之前先读代码确认当前实际行为，别只信限制表。
真正必须给的只有两样：一个能可靠调用工具的模型接入，和一次「你到底要问什么」。agent/SKILL.md 的工具表里被单独标注需要 LLM key 的只有两个条目——多智能体编队 run_swarm，以及重跑失败编队运行的 retry_run，理由是同一个：它们会在内部再拉起工作者。其余工具那一列都是空的。
关于模型选择，README 有一张分档表，把 *-nano、*-flash-lite、小型蒸馏变体明确列进「不建议用于 agent」一档，理由是工具调用不可靠——表现是 agent 看起来在凭训练数据回答，而不是真的去加载技能或跑回测。这类工具密集型 agent 对模型的要求和纯写代码不太一样，先用中间档跑通，再考虑往下降成本。
四、仓库里这些东西各自在哪
下面这张表按「你会在什么时候第一次撞见它」排，路径都是实际存在的目录或文件。括号里的数量是自己在仓库里数得出来的受版本控制文件数或子目录数，不是项目自述数字。
| 组成部分 | 它负责什么 | 仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 交互 CLI / TUI | 终端里的会话循环、命令分发、首屏 banner | agent/cli/（main.py 为入口） | 敲下第一个 vibe-trading |
| 首次配置向导 | 五步问答，原子写出 .env | agent/cli/onboard.py | 第一次启动，或 vibe-trading init |
| 配置样板 | 列出全部可写环境变量与注释 | agent/.env.example | 想知道有哪些开关时 |
| Web / API 服务 | FastAPI 路由：会话、SSE、上传、swarm、alpha | agent/api_server.py 与 agent/src/api/ | 跑 vibe-trading serve 之后 |
| 前端 | React 19 + Vite 的 Web UI（155 个文件） | frontend/ | 浏览器打开 8899 端口时 |
| MCP 服务端 | 把工具集暴露给外部 agent | agent/mcp_server.py | 接进 Claude Desktop / Cursor 等 |
| 技能库 | 金融方法论文档 + 代码模板（88 个目录 / 404 个文件） | agent/src/skills/ | agent 调 list_skills、load_skill 时 |
| 工具层 | agent 可调用的工具实现（72 个文件） | agent/src/tools/ | 几乎每一次研究 |
| 因子库 | 多来源公式的工程化重实现（482 个文件） | agent/src/factors/（各 zoo 子目录带 LICENSE.md） | 用到 alpha 相关命令时 |
| 多智能体编制 | 预置团队的 DAG 定义（30 份 yaml） | agent/src/swarm/presets/ | list_swarm_presets / run_swarm |
| 券商连接器 | 各家券商的读取与下单适配（12 个子目录） | agent/src/trading/connectors/ | 接账户时——最需要停下来想的一步 |
| IM 渠道 | 把会话接进聊天工具（16 个具体渠道实现文件） | agent/src/channels/ | 想让结果推到群里时 |
全仓受版本控制的文件是 2030 个，其中 agent/ 占 1805 个，agent/src/ 下有 23 个模块目录。README 有五个语言版本。这个体量意味着一件事：别指望通读，按上表定位到你当下要改的那一块就够了。
五、边界与代价：它明确不管什么
它不替你承担凭据风险。 配置文件是明文 .env，向导只做到 chmod 0o600 且在失败时静默放过。默认存储根 ~/.vibe-trading 底下同时放着会话、运行产物、swarm 记录、上传文件和索引数据库。也就是说：拿到这个目录，等于拿到你配的所有 key。这台机器的磁盘加密、备份策略、共享账户情况，全都变成了你的暴露面。相关的通用做法见API key 的保管与轮换。
实盘那条路的代价必须说清。 仓库给券商下单加了一整套约束：一个用户提交的授权范围（标的白名单、单笔大小、敞口上限、每日交易次数上限）、文件系统级的即时停止开关、失败即关闭的盘前闸门、完整审计账本；纸面账户与实盘的区分是每家券商各自的结构性运行时守卫（账号格式、主机隔离、demo 标志或交易环境），不是一个 agent 能翻的配置开关；没有这种区分手段的券商被直接限制在纸面加只读。但这些机制约束的是「越界」，不是「下错」。已经成交的委托不会因为你后悔而撤回。README 自己的免责声明写得很清楚：这项券商交易能力是实验性的，维护者未在真实券商账户上验证过，风险自负。另外，程序化交易在不同司法辖区的合规义务差别很大，能不能这么用，以你所在司法辖区的监管要求与券商协议为准。
因子库不是项目自研的。 这一点仓库根目录的 NOTICE 交代得比大多数项目都干净：qlib158 那部分是 Microsoft Qlib 的特征定义，走 Apache 2.0 并锁定了上游 commit SHA；alpha101 来自 Kakushadze (2015) 的公开论文（arXiv:1601.00991）；gtja191 来自国泰君安 2014 年的公开研报；academic 那组对应 Fama-French 五因子等公开模型。NOTICE 明确写着只重实现了数学公式这一「事实性内容」，源论文与研报的正文、表格、图都没有复制，各因子库子目录下另有 LICENSE.md。所以准确的说法是：这是一批公开公式的工程化重实现，不是一套私有方法。本文不提供法律意见，能不能商用以许可证原文为准；同时，历史表现不代表未来，本文只讨论工程实现。
生成代码是跑在真的子进程里的。 回测代码作为本地 Python 子进程执行，可以通过配置好的行情加载器发起网络请求。仓库把它的环境刻意收窄了：只传 OS/Python 基础变量、代理与证书设置、VIBE_TRADING_ALLOWED_RUN_ROOTS，以及 TUSHARE_TOKEN、FMP_API_KEY、FRED_API_KEY、VIBE_TRADING_IWENCAI_KEY 这类只读行情密钥；默认不把 LLM provider 密钥、API 鉴权 token、shell 工具开关、券商交易密钥传给生成的策略代码。这是个值得学的最小权限切法，思路和给 agent 设计最小权限那篇是一致的。但边界仍在：它是子进程隔离，不是沙箱化的容器隔离。
它不管你的判断。 这套东西给的是可复现的流程和可检查的产物——工具轨迹、运行卡、校验文件。至于结论对不对、要不要照做，仓库自己在免责声明里说了：不是投资建议，不持有资金，不运营交易场所。
六、上手清单：会踩的坑与怎么避
1. 两份 .env 同时存在，你改的那份不生效。 为什么会踩：.env 的搜索顺序是 ~/.vibe-trading/.env → agent/.env → $CWD/.env，第一个存在的胜出；而 Docker 与本地安装两条路径的文档都让你 cp agent/.env.example agent/.env，首次向导写的却是第一优先级的那份。两份同时存在时，你在 agent/.env 里改的 key 会被无声忽略。怎么避：装完先确认到底有几份，只保留一份；不确定就删掉次优先级那份重跑 vibe-trading init。
2. 在 shell 里 export 环境变量，MCP 那边完全收不到。 为什么会踩：MCP 客户端是自己拉起服务端子进程的，你终端里的 export 不在它的环境里。README 专门为此写了一段。怎么避：把变量写进客户端配置里那个服务器条目的 env 块，比如要让生成的回测结果落到你自己的工作目录，就得在 env 里给 VIBE_TRADING_ALLOWED_RUN_ROOTS。
3. 把 VIBE_TRADING_HOME 写进 .env，结果一半路径生效一半不生效。 为什么会踩：这是个反直觉的时序问题——.env.example 的注释直接点名了，路径常量在进程启动时就解析完了，早于这个文件被读取，所以写在这里只会对部分代码路径起作用。怎么避：这一个变量必须设在 shell 环境里（export VIBE_TRADING_HOME=...），别写进配置文件。
4. 创建了定时研究任务，到点什么都没发生。 为什么会踩：后台执行器默认关闭。不开的时候 /scheduled-runs 端点仍然照常记录任务，只是永远不触发——看起来像成功了。怎么避：用 VIBE_TRADING_ENABLE_SCHEDULER=1 vibe-trading serve 启动；建了任务之后回头确认一次是否真的跑过。
5. 从别的机器打开 Web UI，页面出来了但功能全 403。 为什么会踩：serve 绑的是 0.0.0.0，所以页面能加载，但敏感端点只认回环来源。这个组合最容易让人以为是 bug。怎么避：设置 API_AUTH_KEY 后重启，并在 Settings 页里输入同一个 key；Docker Desktop 的宿主网关场景另有 VIBE_TRADING_TRUST_DOCKER_LOOPBACK 这个开关配合默认的 127.0.0.1 端口绑定使用。
6. 密钥前缀不对，向导直接打回。 为什么会踩：_validate_key 会按 provider 声明的前缀做字符串校验，把 OpenRouter 的 key 填进 OpenAI 那一格必然被拒。报错信息本身是准的，但在掩码输入框里人容易怀疑自己粘错了。怎么避：先看清当前选的是哪个 provider，再粘对应的 key；拿不准就 Esc 回退一步重选。
7. 通过 API 往会话里塞 MCP server 定义，被静默丢弃。 为什么会踩：mcpServers 能定义子进程的 command/args/env，属于操作者级信任，所以默认禁止 API 调用方注入，且是静默剥离而非报错。怎么避：确实需要就在服务端启动前设 ALLOW_SESSION_MCP_SERVERS=1；不需要就别浪费时间调试为什么没生效。磁盘上的全局配置 ~/.vibe-trading/agent.json 不受这个开关影响，始终生效。
8. 装完直接接实盘。 为什么会踩：这套东西跑起来太顺，容易让人一路点下去。怎么避：把「接券商」当成一个独立决策，和「跑通研究」隔开至少几天。研究路径不需要任何券商凭据就能走完，先把这条走透。
收个尾
一句话自检：跑完第一次研究之后，你应该能回答出这几个问题——我的 .env 到底在哪一份、里面有哪些 key；我现在用的是哪个入口、它默认开了哪些工具；如果这台机器丢了，泄露的是什么；我有没有在还没想清楚之前就把券商接上去。
接下来该读哪个文件，取决于你要往哪走。想扩配置就通读 agent/.env.example，它比任何文档都全，且注释里写了每一项的时序陷阱；想搞清楚能力边界就读 agent/SKILL.md 的工具表和 API key 需求表；想接自己的 MCP 服务器就直接看 README 的 MCP 客户端模式一节，重点在那张失败处理表和 v1 限制列表——串行执行和不支持热重载这两条会直接影响你的调试节奏。
本篇属于一个把开源个人交易 Agent 项目 Vibe-Trading逐层拆开讲的系列，整体地图见 Vibe-Trading 是什么：HKUDS 这个开源交易 Agent 项目的工程全景与边界；沿着这条线往下，还可以看 Vibe-Trading 开源项目跑不起来：自检表、限额与数据源降级 和 Vibe-Trading 开源项目怎么接大模型：能力表与登录态通道。