环境变量参考¶
本文列出 daemon (futu-opend) / CLI (futucli / futu-mcp) 支持的全部
FUTU_* 环境变量, 用途, 默认值, 与配套 CLI flag.
凭据 (Credentials)¶
| Env var | 用途 | 默认 | 配套 CLI flag |
|---|---|---|---|
FUTU_ACCOUNT |
登录账号 hint。futucli unlock-trade / futu-mcp 未传 --trade-pwd-account 时可用它选择账号级交易密码；部分 helper 脚本也用它启动 daemon |
(按需) | daemon 请优先用 --login-account <ACCOUNT> |
FUTU_PWD |
登录密码 (明文 / 32-hex MD5 自动判别) | (必填或用 CLI flag) | --login-pwd <PWD> |
FUTU_TRADE_PWD |
交易解锁密码 (futucli unlock / MCP unlock) | (按需) | --trade-pwd <PWD> |
FUTU_TRADE_PWD_ACCOUNT |
账号级交易密码 keychain lookup 的账号 hint | (按需) | --trade-pwd-account <ACCOUNT> |
FUTU_API_KEY |
futucli stock-note-labels / stock-notes / set-stock-note 转发到 OpenD REST，以及逐笔资金流 CLI 连接原生二进制 WebSocket 时使用的 Bearer token |
(安全 KeyStore 模式按需) | futucli ... --api-key <KEY> |
FUTU_MCP_API_KEY |
futu-mcp --keys-file stdio scope 模式的进程级默认 API key；HTTP scope 模式不使用该值兜底，每个 /mcp 请求必须自带有效 Authorization: Bearer |
(stdio scope 模式必填；HTTP 不适用) | futu-mcp --api-key <KEY> |
FUTU_MCP_OPEND_REST_URL |
futu-mcp 受保护真实资金写工具（组订单 / 算法单 / 仓位复合动作）在 daemon 关闭裸 TCP（安全 KeyStore 模式）时转发到的 OpenD REST base URL；未设置时这些写工具拒绝执行 |
(按需；仅安全部署) | futu-mcp --opend-rest-url <URL> |
安全提示: 推荐用 systemd EnvironmentFile=/etc/futu-opend.env (mode 0600)
传, 不在 shell history / ps aux 暴露明文.
MCP 协议诊断¶
| Env var | 用途 | 默认 | 配套 CLI flag |
|---|---|---|---|
FUTU_MCP_PROTOCOL_DIAGNOSTICS |
启用 MCP 协议验收诊断工具；保留现有鉴权，配置 --keys-file 时需要 qot:read。CLI、环境变量、TOML protocol_diagnostics、默认值按顺序取值；显式 false 可关闭 |
false |
futu-mcp --protocol-diagnostics[=true\|false] |
连接地址 (Connection)¶
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_GATEWAY |
MCP / futucli 连 daemon 的 gRPC 地址 | 127.0.0.1:11111 |
FUTU_REST_URL |
futucli 连 daemon 的 REST URL | http://127.0.0.1:11112 |
FUTU_WS_URL |
逐笔资金流 CLI 读取与订阅命令的原生二进制 WebSocket URL（ws:// / wss://），等价于 --ws-url；调用者 Key 由 --api-key / FUTU_API_KEY 提供 |
无默认值，必须显式提供 |
FUTU_MCP_TAPE_WS_URL |
futu-mcp 逐笔资金流读取与流订阅使用的原生二进制 WebSocket URL，等价于 --tape-ws-url；保留调用者权限和市场限制，连接时仍需有效 Bearer Key |
无默认值；未设置时拒绝对应读取或新建流 |
FUTU_ADDR |
examples/live_test 用的 daemon 地址 | 127.0.0.1:11111 |
上游 CA 与代理¶
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_UPSTREAM_CA_FILE |
显式指定可信 PEM 证书文件，追加到普通上游 HTTP/WebTCP 的内置 Mozilla 根证书 | 未设置；不加载环境或系统 CA |
FUTU_UPSTREAM_PROXY |
普通上游 HTTPS、WebTCP 与后端 TCP 的 HTTP 代理 URL，只支持 http://；代理认证可使用百分号编码的 URI 用户信息 |
未设置；保留现有 HTTP 环境代理与 TCP 直连 |
配置首次使用后在进程内冻结，修改后需重启 daemon。指定文件不存在、为空或含无效证书，以及不支持的代理配置，均直接报错，不回退到其他配置。证书链、有效期和域名仍严格验证。
显式代理覆盖继承的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY，HTTPS/WebTCP/后端 TCP 使用 CONNECT，拒绝或超时后不绕回直连。自定义 http:// 认证地址沿用 HTTP forward；HTTPS 的 CONNECT 使用域名，重试 IP 配置不保证代理实际连接该 IP。代理可以限制目标端口，仅允许 HTTPS 443 的代理未必允许普通后端 TCP 端口。
WebTCP 经显式代理时发送与证书验证域名一致的 SNI，供代签代理选择正确证书；CONNECT 目标仍由现有连接配置提供。直连 WebTCP 不发送 SNI，两条路径都严格验证证书。
平台登录日志中，write_completed（INFO）只证明本地完整帧写入和 flush 成功，write_failed（WARN）表示写出失败。使用 serial_no、connection_generation、endpoint_fingerprint 关联请求；frame_bytes 为帧长度，失败时不表示已写出的字节数。日志不含请求体、账号、原始端点或原始错误文本。写出完成后仍超时且 received_bytes=0 时，请结合代理或后台记录检查转发和回应；本地完成不证明后台已收到请求。
VM 已有环境证书和 HTTP 代理时，可由操作者显式选择：
export FUTU_UPSTREAM_CA_FILE="$SSL_CERT_FILE"
export FUTU_UPSTREAM_PROXY="$HTTPS_PROXY"
futu-opend --setup-only
请确认所选变量非空、PEM 文件可信且可读，代理 URL 为 http://。含凭证的配置用受保护的环境文件提供，不放入公开日志。两项可分别设置；不影响本地 REST/MCP TLS、更新检查或银行原生传输。
浏览器入口 / Metrics 安全¶
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_REST_ALLOWED_ORIGINS |
REST CORS Origin allowlist, 逗号分隔；* / any / all 表示开发用 wildcard |
已配置 REST key 时只允许 loopback；legacy unauth 模式保持 wildcard 兼容 |
FUTU_WS_ALLOWED_ORIGINS |
WebSocket handshake Origin allowlist, 逗号分隔 | 未设置时只允许 loopback Origin；非浏览器客户端无 Origin 时不走此检查 |
FUTU_METRICS_PUBLIC=1 |
/metrics 回退为公开访问并保留明文 key_id label |
默认按 auth posture 保护 /metrics，且 metrics 中 key_id redacted |
生产建议：
- Browser UI 场景显式配置 exact origin，例如
https://app.example.com。 FUTU_METRICS_PUBLIC=1只建议在 metrics 端口由防火墙 / sidecar 严格保护时使用。
长跑 daemon 加固 (Long-running hardening, v1.4.103+)¶
兼容 env opt-in, default OFF。也可以用 futu-opend
--client-sig-proactive-refresh / --client-sig-reactive-refresh 或 TOML
client_sig_proactive_refresh = true / client_sig_reactive_refresh = true
打开。详细见
长跑 daemon 部署指南.
| Env var | 用途 | 默认 | 风险 |
|---|---|---|---|
FUTU_CLIENT_SIG_PROACTIVE_REFRESH=1 |
在 client_sig 失效前 1h 主动调 refresh |
OFF | 低 — 单次 refresh 行为；请先用非关键账户验证服务端接受度 |
FUTU_CLIENT_SIG_REACTIVE_REFRESH=1 |
tcp_login 持续失败 (≥3 次) 时反应式 refresh | OFF | 中 — ret_type=15 含义不止 client_sig 失效 (含反刷限流 / 风控), 多账号 daemon 误 refresh 可能影响其他账号; 单账号场景安全 |
FUTU_QOT_RELOGIN_BACKOFF_MS |
QOT login health 自愈 ladder, 4 个毫秒值: fail0,fail1,fail2,fail3+ |
60000,120000,240000,600000 |
中 — 只给真机验证 / 长跑排障调短；生产不建议频繁 relogin |
FUTU_WEBSIG_REFRESH |
WebSig 主动刷新总开关；只在紧急回滚时设为 0 / false / no / off，改动后重启 daemon |
ON | 高 — 关闭后 WebSig 过期只能依赖失败后的重连/换票恢复 |
FUTU_SESSION_KEY_REFRESH |
控制 C++ 对齐的 TCP session-key 周期刷新 actor；刷新失败会使当前连接失效并进入统一重连 | ON；仅 0 / false / no / off 关闭 |
低 — 紧急停用阀，正常运行无需设置 |
FUTU_WEBTCP_SITE_CONFIG_REFRESH |
启用 WebTCP site-config 的周期刷新 timer；关闭时仍会首拉，并在 commconfig 目标变化后重拉 | OFF，仅 1 / true / yes / on 开启 |
低 — last-good 会继续保留 |
何时将两个 client-sig 开关切为 default ON：需要足够的真实部署样本证明
FUTU_CLIENT_SIG_PROACTIVE_REFRESH 和
FUTU_CLIENT_SIG_REACTIVE_REFRESH 不会触发额外限流或风控。这两个开关当前
仍是 experimental opt-in；本段不适用于表中已经默认开启的 WebSig 和 session-key
刷新。
客户端 (CLI / SDK / MCP)¶
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_CLI_AUTO_IDEM=1 |
futucli 自动派生 idempotency_key (基于参数 hash) — place-order/modify/cancel | OFF |
FUTU_UPDATE_CHECK_URL |
futucli version --check / futucli doctor 更新检查的 version.json URL 覆盖 |
未设置时用 https://futuapi.com/version.json；入口不可用、非 2xx 或 schema 不兼容时 fail closed |
启动与本地缓存¶
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_STOCK_LIST_STARTUP_WAIT_SECS |
本地股票列表为空时，ready 前等待首轮 stock-list sync 的秒数；超时后后台继续同步 | 3；0 表示不等待 |
FUTU_LANGUAGE_PACK_CACHE_DIR |
语言包 manifest / last-good cache 根目录 | OS cache dir 下的 futu-opend-rs/language-packs |
行情配额调试¶
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_HISTORY_KLINE_CLOUD_SYNC |
是否与官方 OpenD/App 同步历史 K 线已使用额度；仅接受 true / false |
true；可用 --history-kline-cloud-sync false 或配置项 history_kline_cloud_sync = false 进入只使用本地额度的兼容模式 |
FUTU_HISTORY_KL_QUOTA_MAX |
覆盖本进程历史 K 线 quota 周期内可请求的唯一 stock 数上限；未设置时跟随账号动态额度 | 未设置（冷启动回退 100） |
FUTU_HISTORY_KL_QUOTA_PERIOD_SECS |
历史 K 线 quota 周期长度 (秒) | 604800 (7 天) |
说明：历史 K 线总额度优先使用登录后 后端请求 返回的账号动态额度（例如官方 OpenD UI 展示的历史 K 线额度）。FUTU_HISTORY_KL_QUOTA_MAX 只用于显式覆盖 / 压测 / 调试；冷启动且尚未拿到动态额度时会先按 C++ 默认值 100 fail-closed。
交易诊断¶
FUTU_TRADE_PUSH_DIAGNOSTICS 默认关闭，首次使用后冻结；设为 1、true、yes 或 on 启用。daemon 增加 --json-log 并使用 INFO 日志级别；本版 Rust SDK 接收程序也需启用该变量并初始化 INFO 级 JSON 日志。修改后重启对应进程。
诊断关联通知解析、重查、缓存决策、订阅/权限过滤及原生 TCP/WS 写出和接收。写出完成、帧接收、完整性校验及本地队列接纳是不同事实，队列接纳不代表应用消费；REST WebSocket/gRPC 只记录适配器交接，其它 SDK 需记录匹配的接收字段。包内 scripts/trade_push_diagnostics.py 离线读取 JSONL，明确绑定同一连接观察窗口的 daemon/receiver run_id；跨运行帧号冲突保持歧义，未匹配接收记录保留未知归属。只回传工具的字段白名单汇总，普通原始日志可能包含业务信息；不需要新增交易。
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_HISTORY_ORDER_AUDIT=1 |
打开 history-orders backend row 过滤 / 投影审计日志，用于排查 Rust 与官方 C++ history order 数量或字段差异 | OFF |
FUTU_TRADE_PUSH_DIAGNOSTICS |
启用交易通知到原生 TCP/WS writer 与本版 Rust SDK 接收的关联诊断；使用 INFO JSON 日志 | OFF |
账户设置开关¶
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_ACCOUNT_FUNDING_SETTINGS_WRITES |
允许显式修改账户融资、换汇及自动换汇设置；独立于通用 --extended-data-writes，原账户能力、调用权限和结果读回检查仍适用 |
OFF；仅 1 或不区分大小写的 true 开启 |
测试 / Chaos engineering¶
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_E2E_SIM_ACC |
E2E 测试用 sim 账号 | (test-only) |
FUTU_E2E_SIM_PWD |
E2E 测试用 sim 密码 | (test-only) |
FUTU_E2E_SIM_PLATFORM |
E2E 测试 platform (futunn / moomoo) |
futunn |
FUTU_CHAOS_ENABLE=1 |
chaos test 故障注入开关 | OFF |
FUTU_MULTI_VERSION_GUARD_STRICT=1 |
multi_version_smoke.sh 严格模式 (binary fingerprint diff 命中 → exit 1) | (ship.sh A9 自动设) |
Release tooling¶
| Env var | 用途 |
|---|---|
FUTU_MULTI_VERSION_GUARD_STRICT=1 |
A9 stage 强设, ship-blocker fail 阻塞发版 |
FUTU_MV_CACHE_DIR |
scripts/multi_version_smoke.sh 下载历史二进制的缓存目录 |
Build metadata¶
| Env var | 用途 | 默认 |
|---|---|---|
FUTU_OPEND_RS_GIT_SHA |
覆盖编译进 device_alias / 版本诊断里的 git SHA |
build script 自动读取 git rev-parse --short HEAD |
命名约定¶
FUTU_<SUBSYSTEM>_<FEATURE>_<ACTION>=<VALUE>:
FUTU_prefix — 所有 daemon / CLI / SDK 共享 namespace- subsystem:
CLIENT_SIG/TRADE/CLI/E2E/CHAOS等 - feature/action: 描述功能本身, 不暴露内部编号 (例如不用
INTERNAL_123, 而用PROACTIVE_REFRESH描述行为) - value: 按对应条目解析；各开关接受的布尔值与默认状态不同
与 CLI flag 的关系¶
一般优先级为 CLI flag > env var > 配置文件 > 内置默认；具体功能如有兼容性约束，
以对应条目为准。FUTU_HISTORY_KLINE_CLOUD_SYNC 的优先级是 CLI > 配置文件 > env >
默认 true。
例: FUTU_PWD=foo futu-opend --login-pwd bar → 用 bar (CLI flag).