幫助與更新

集中排查安裝、授權、數據和交易調用問題，並查看版本更新、終端補全與請求診斷説明。

故障排查

先按出現問題的階段查找，再進入對應説明。

安裝與命令發現

提示	處理方式
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 標識當前會話；當前版本未提供關閉上報的配置項。