TradingAgents-CN 在线工具配置指南：用三个环境变量精细控制在线/离线分析模式

TradingAgents-CN 在线工具配置指南：用三个环境变量精细控制在线/离线分析模式

【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN

TradingAgents-CN 通过ONLINE_TOOLS_ENABLED、ONLINE_NEWS_ENABLED、REALTIME_DATA_ENABLED三个环境变量，将系统的"在线行为"从 LLM 提供商（如 OpenAI）的启用状态中彻底解耦，实现对数据获取工具的独立精细控制。本文以 docs/configuration/online-tools-config.md 为核心骨架，结合 tradingagents/default_config.py 的默认配置实现、tradingagents/graph/trading_graph.py 的工具节点构建逻辑以及仓库测试脚本，完整讲解三种配置模式的适用场景、三种配置方法、工具影响范围、迁移指南与故障排查，帮助你按需在功能需求与 API 成本之间找到最佳平衡。

配置机制概述

在早期版本中，系统的在线状态与OPENAI_ENABLED等 LLM 提供商开关强耦合：关闭某个提供商，连同其配套的数据获取工具也会一并失效。新的配置系统则把"是否调用外部 API 获取数据"提升为独立的控制维度，从源码实现看，这一设计体现在 tradingagents/default_config.py：

# Tool settings - 从环境变量读取，提供默认值 "online_tools": os.getenv("ONLINE_TOOLS_ENABLED", "false").lower() == "true", "online_news": os.getenv("ONLINE_NEWS_ENABLED", "true").lower() == "true", "realtime_data": os.getenv("REALTIME_DATA_ENABLED", "false").lower() == "true",

即三个配置项在模块加载时直接读取环境变量，并把字符串解析为布尔值。注意默认值：ONLINE_TOOLS_ENABLED与REALTIME_DATA_ENABLED默认关闭，ONLINE_NEWS_ENABLED默认开启，意味着项目默认处于"新闻在线、行情与工具离线"的混合状态。

主要配置字段

配置优先级

1. 环境变量（.env 文件）— 最高优先级，启动时由 tradingagents/default_config.py 读取并覆盖默认值；
2. 默认配置（default_config.py）— 备用默认值，仅在环境变量未设置时生效。

需要留意的是，环境变量只有在模块加载时才会被读取，因此修改.env或执行export后必须重启进程才会生效。测试脚本tests/0.1.14/test_tool_selection_logic.py中通过importlib.reload(tradingagents.default_config)的方式重新加载模块来模拟环境变量变更，也印证了这一运行期读取机制。

三种典型配置模式

1. 开发模式（完全离线）

# .env 文件配置 ONLINE_TOOLS_ENABLED=false ONLINE_NEWS_ENABLED=false REALTIME_DATA_ENABLED=false

特点：

• ✅ 完全使用缓存数据
• ✅ 零 API 调用成本
• ✅ 适合开发和调试
• ❌ 数据可能不是最新的

2. 测试模式（部分在线）

# .env 文件配置 ONLINE_TOOLS_ENABLED=false ONLINE_NEWS_ENABLED=true REALTIME_DATA_ENABLED=false

特点：

• ✅ 新闻数据实时获取
• ✅ 股价数据使用缓存
• ✅ 平衡功能和成本
• ✅ 适合功能测试

3. 生产模式（完全在线）

# .env 文件配置 ONLINE_TOOLS_ENABLED=true ONLINE_NEWS_ENABLED=true REALTIME_DATA_ENABLED=true

特点：

• ✅ 获取最新实时数据
• ✅ 适合实盘交易
• ❌ API 调用成本较高
• ❌ 需要稳定网络连接

这三个开关是相互独立的维度而非互斥枚举，因此可以组合出更多中间状态（例如只开实时行情、只开新闻等），实现比三档模式更细粒度的控制。仓库测试脚本 tests/0.1.14/test_tool_selection_logic.py 就定义了四个典型场景来验证工具选择逻辑：

三种配置方法

方法 1：修改 .env 文件（推荐）

# 编辑 .env 文件 nano .env # 添加或修改以下配置 ONLINE_TOOLS_ENABLED=true ONLINE_NEWS_ENABLED=true REALTIME_DATA_ENABLED=false

项目根目录提供了.env.example作为配置模板（复制为.env后填写），其中包含完整的 MongoDB、Redis、JWT、各大 LLM 厂商密钥与数据源密钥配置。注意：布尔值解析支持true/True/TRUE/1/yes/on等格式（见 .env.example 中的注释说明），解析逻辑统一走os.getenv(...).lower() == "true"。

方法 2：环境变量设置

# Windows PowerShell $env:ONLINE_TOOLS_ENABLED="true" $env:ONLINE_NEWS_ENABLED="true" $env:REALTIME_DATA_ENABLED="false" # Linux/macOS export ONLINE_TOOLS_ENABLED=true export ONLINE_NEWS_ENABLED=true export REALTIME_DATA_ENABLED=false

方法 3：代码中动态配置

from tradingagents.default_config import DEFAULT_CONFIG # 创建自定义配置 config = DEFAULT_CONFIG.copy() config["online_tools"] = True config["online_news"] = True config["realtime_data"] = False # 使用自定义配置 from tradingagents.graph.trading_graph import TradingAgentsGraph ta = TradingAgentsGraph(config=config)

这一方式是仓库内各入口实际采用的做法。从源码结构看，app/services/simple_analysis_service.py 与 web/utils/analysis_runner.py 在创建分析任务时都会执行config = DEFAULT_CONFIG.copy()再写入config["online_tools"] = True，以确保各级分析深度统一使用在线工具、避免离线工具引发的数据源问题；main.py 示例同样在复制默认配置后覆盖online_tools。而Toolkit类（tradingagents/agents/utils/agent_utils.py）以类属性_config = DEFAULT_CONFIG.copy()持有配置，并通过update_config()合并传入的配置，TradingAgentsGraph在初始化时执行self.toolkit = Toolkit(config=self.config)（tradingagents/graph/trading_graph.py）将运行时配置注入工具集。

配置验证

使用测试脚本验证

python tests/0.1.14/test_online_tools_config.py

该脚本依次完成四项检查（见 tests/0.1.14/test_online_tools_config.py）：

1. 环境变量检查：读取ONLINE_TOOLS_ENABLED、ONLINE_NEWS_ENABLED、REALTIME_DATA_ENABLED、OPENAI_ENABLED四个变量的当前值；
2. 配置文件测试：从DEFAULT_CONFIG中读取online_tools、online_news、realtime_data三个键值；
3. 配置逻辑验证：根据三个布尔值判断当前属于"离线模式 / 完全在线 / 混合模式"，并对"新闻已启用但总开关关闭"的组合给出建议提示；
4. 工具包集成测试：实例化Toolkit(config=DEFAULT_CONFIG)，逐一检查get_google_news、get_reddit_news、get_reddit_stock_info、get_chinese_social_sentiment四个在线工具的可用性。

另外，tests/0.1.14/test_tool_selection_logic.py中的test_trading_graph_integration还会创建真实的TradingAgentsGraph实例并检查ta.tool_nodes["market"]、ta.tool_nodes["news"]、ta.tool_nodes["social"]的工具数量与主要工具名称，用于端到端验证配置如何影响实际绑定的工具。

手动验证配置

from tradingagents.default_config import DEFAULT_CONFIG print("当前配置:") print(f"在线工具: {DEFAULT_CONFIG['online_tools']}") print(f"在线新闻: {DEFAULT_CONFIG['online_news']}") print(f"实时数据: {DEFAULT_CONFIG['realtime_data']}")

工具影响范围

受ONLINE_TOOLS_ENABLED控制的工具

• 所有需要 API 调用的数据获取工具
• 实时股价数据获取
• 在线技术指标计算

从图构建源码（tradingagents/graph/trading_graph.py）可以看出，各 ToolNode 中"在线工具（备用）"与"离线工具（备用）"是成对注册的：市场节点同时注册get_YFin_data_online/get_stockstats_indicators_report_online（在线）与get_YFin_data/get_stockstats_indicators_report（离线）；社交节点注册get_stock_news_openai（在线）与get_reddit_stock_info（离线）。结合test_tool_selection_logic.py的断言，开关影响的是各节点实际被 LLM 选择的主用工具。

受ONLINE_NEWS_ENABLED控制的工具

• get_google_news— Google 新闻获取（agent_utils.py 实现，内部调用interface.get_google_news(query, curr_date, 7)回溯 7 天）
• get_reddit_news— Reddit 新闻获取（agent_utils.py）
• get_reddit_stock_info— Reddit 股票讨论（agent_utils.py）
• get_chinese_social_sentiment— 中国社交媒体情绪（agent_utils.py），整合雪球、东方财富股吧、新浪财经等本土平台，失败时自动回退到 Reddit 数据

受REALTIME_DATA_ENABLED控制的工具

• 实时股价数据
• 实时市场指数
• 实时交易量数据

配置冲突处理与注意事项

1. 配置冲突处理

• 如果ONLINE_TOOLS_ENABLED=false但ONLINE_NEWS_ENABLED=true，新闻工具仍然可用——这种设计允许更精细的控制，也是"测试模式"得以成立的基础。test_tool_selection_logic.py的场景 3 正是验证该组合：市场走离线get_YFin_data，新闻走在线get_google_news。

2. API 配额管理

• 在线模式会消耗 API 配额
• 建议在开发阶段使用离线模式
• 生产环境根据需要选择合适的模式

需要说明的是：当前仓库的ONLINE_TOOLS_ENABLED开关主要作用于工具选择逻辑，而统一工具（如get_stock_fundamentals_unified、get_stock_market_data_unified、get_stock_sentiment_unified）内部会自动识别股票类型（A股/港股/美股）并按优先级选择数据源（A股：MongoDB → Tushare → AKShare → BaoStock；港股：AKShare → Yahoo Finance；美股：Yahoo Finance → FinnHub），各数据源自身的 API 密钥配置请参考 .env.example 中TUSHARE_TOKEN、FINNHUB_API_KEY、REDDIT_CLIENT_ID等字段。

3. 网络依赖

• 在线模式需要稳定的网络连接
• 网络异常时会自动回退到缓存数据

仓库中确实存在多处"失败回退"设计，例如get_chinese_social_sentiment在中国平台数据获取失败时回退到interface.get_reddit_company_news(...)，以及统一工具内部的多数据源自动切换，均体现了这一容错原则。

从旧配置迁移

如果您之前使用的是基于OPENAI_ENABLED的配置：

旧方式：

OPENAI_ENABLED=false # 这会影响整个系统的在线状态

新方式：

OPENAI_ENABLED=false # 只控制 OpenAI 模型 ONLINE_TOOLS_ENABLED=false # 专门控制在线工具 ONLINE_NEWS_ENABLED=true # 精细控制新闻工具

迁移的本质是职责分离：OPENAI_ENABLED只决定是否启用 OpenAI 模型推理，数据的在线获取改由专门开关管理。从仓库演化记录看，docs/fixes/2025-10-11_remove_online_tools_config.md 记载了在线/离线双套工具曾引发的 LLM 死循环问题（LLM 在get_china_stock_data与get_china_fundamentals两个工具间反复调用、报告长度始终为 0），最终通过统一工具方案解决；这解释了为什么当前代码中基本面分析师等固定绑定统一工具（见 fundamentals_analyst.py），而三个环境变量开关负责的是备用工具的选择倾向。另外，后端兼容层 app/core/config_compat.py 提供的默认系统设置中online_tools与online_news默认即为true，也保持了新旧系统之间的行为一致性。

最佳实践速查

故障排除

常见问题

1. 配置不生效

   • 检查 .env 文件是否正确加载（确认文件位于项目根目录且已复制自.env.example）
   • 确认环境变量格式正确（true/false）
   • 确认修改后已重启进程（环境变量仅在模块加载时读取）

2. 工具调用失败

   • 检查相关 API 密钥是否配置（Tushare Token、Finnhub Key、Reddit 凭据等）
   • 确认网络连接是否正常
   • 在线数据源不可用时系统会尝试回退到备用数据源或缓存

3. 数据不是最新的

   • 确认REALTIME_DATA_ENABLED=true
   • 检查数据源 API 是否正常

调试命令

# 检查当前配置 python -c "from tradingagents.default_config import DEFAULT_CONFIG; print(DEFAULT_CONFIG)" # 测试配置系统 python tests/0.1.14/test_online_tools_config.py # 测试工具选择逻辑（四种场景 + TradingGraph 集成） python tests/0.1.14/test_tool_selection_logic.py # 检查环境变量 echo $ONLINE_TOOLS_ENABLED echo $ONLINE_NEWS_ENABLED echo $REALTIME_DATA_ENABLED

总结

通过这套独立的在线工具配置系统，TradingAgents-CN 将"数据获取的在线行为"从 LLM 提供商配置中解耦出来：ONLINE_TOOLS_ENABLED控制数据获取工具总开关，ONLINE_NEWS_ENABLED独立控制新闻与情绪类工具，REALTIME_DATA_ENABLED控制实时行情数据。三档典型模式（开发离线、测试混合、生产全在线）覆盖了从零成本调试到实盘交易的全部场景，而配置冲突处理、自动回退与故障排查机制则保证了系统在弱网或 API 限流情况下的可用性。无论你是通过 .env 文件、shell 环境变量还是代码动态配置，都可以在功能需求与 API 成本之间找到精确的平衡点。

【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN