帮助与更新

集中排查安装、授权、数据和交易调用问题，并查看版本更新、终端补全与请求诊断说明。

故障排查

先按出现问题的阶段查找，再进入对应说明。

安装与命令发现

提示	处理方式
futu: command not found	重新打开终端，检查安装目录是否已加入 PATH
openssl is required to verify the release signature	安装 OpenSSL，并确保终端可运行 openssl
npm 安装提示 spawn sh ENOENT	macOS / Linux 可运行 npm config set script-shell /bin/sh 后重试
npm 安装提示 uv_cwd 或 getcwd	先运行 cd ~，再从有效目录重新安装
nvm 环境中安装后找不到命令	检查 node 和 npm 是否来自同一 Node.js 安装，并检查全局安装路径
终端能用，AI 工具找不到命令	检查 AI 工具实际执行命令的环境，确认可执行文件路径；桌面应用可能不继承终端 PATH

macOS / Linux 可用 command -v futu 查找可执行文件，PowerShell 可用 (Get-Command futu).Source。必要时在 AI 工具中使用完整路径。远程服务器或容器需在各自环境中完成安装与登录。

授权与连接

问题	下一步
缺少 client_id、未登录或 Token 无法刷新	首次使用按初始化与登录完成配置；已有配置时重新登录授权
登录正常，但 connectivity.api.ok 为 false	检查网络、代理和 API 地址，按连接检查查看详细结果
HTTP 可达，但业务查询失败	查看接口返回的错误说明，核对账户的接口及市场权限；本地登录状态不能代表所有业务权限
无浏览器环境无法完成授权回调	按 SSH 登录说明处理本地回调或手动粘贴完整回调 URL

数据与脚本

问题	下一步
JSON 解析失败，或错误文本混入结果	先检查退出码，分开处理 stdout 与 stderr；参见在脚本中读取 JSON
字段缺失、零值未返回或结果不完整	按 JSON 输出约定核对零值省略、skipped 和分页信息，不要统一补零
历史行情只返回一部分	按历史 K 线与分页继续读取，并核对日期范围与游标
股票筛选结果为空	核对筛选条件与返回结构；参见股票筛选示例

交易调用

问题	下一步
返回了预览，但找不到订单	预览尚未提交；按交易预览与提交核对确认步骤
交易命令等待 y/n 输入	可能是券商二次确认；由用户核对提示后处理，详见交易确认流程
提交成功，但未完成订单中没有记录	通过订单详情与历史确认最终状态；提交成功不等于已成交

查看命令帮助

futu --help
futu order buy --help
futu stock-screen --help

更新 CLI

先查看当前版本：

futu version

脚本安装的 CLI 可通过以下命令检查和安装最新稳定版：

futu update --check
futu update

futu update 会校验下载包的签名和校验和。auto_update 控制自动检查和提示，更新安装需运行 futu update。

通过 GitHub npm 安装的用户，重新运行安装命令进行更新：

npm install -g github:FutunnOpen/futu-cli --install-links=true

终端补全

为当前终端会话加载命令补全：

Bash：

source <(futu completion bash)

Zsh：

source <(futu completion zsh)

Fish：

futu completion fish | source

PowerShell：

futu completion powershell | Out-String | Invoke-Expression

持久化补全的配置方式可运行 futu completion --help 查看。

请求诊断信息

CLI 会将 API 调用诊断信息上报至 https://ai-report.futunn.com，用于定位失败或响应缓慢的请求。信息包括命令名称、接口路径、状态码、耗时、CLI 版本、运行平台、Agent 名称，以及经过处理的请求和响应。

Token、密码和密钥字段会脱敏；证券交易、账户和加密货币交易载荷会进行掩码处理。行情等其他请求会保留其余业务字段。上报请求使用同一 OAuth access token 标识当前会话；当前版本未提供关闭上报的配置项。