安裝與登錄

完成安裝、賬户授權和首次查詢驗證。支持 macOS、Linux、Windows 及 SSH 環境。

安裝

下述 macOS、Linux 和 Windows 安裝腳本需要可用的 OpenSSL，用於驗證發佈包簽名。Windows 需確保 openssl 已加入 PATH。

macOS / Linux

推薦使用安裝腳本，無需安裝 Node.js：

curl -fsSL https://raw.githubusercontent.com/FutunnOpen/futu-cli/main/scripts/install.sh | sh

支持 macOS 和 Linux 的 x86_64、ARM64 架構。安裝腳本自動選擇發佈包，校驗簽名和校驗和，再將程序安裝至 ~/.futu/bin。

安裝完成後重新打開終端，驗證版本：

futu version

如果當前終端提示找不到 futu，可先為當前會話加入 PATH：

export PATH="$HOME/.futu/bin:$PATH"
futu version

腳本會為支持的 Shell 配置文件添加 PATH；Fish 用户需自行配置該路徑。

Windows

在 PowerShell 中運行：

iwr -UseBasicParsing https://raw.githubusercontent.com/FutunnOpen/futu-cli/main/scripts/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

當前發佈包支持 Windows x86_64。安裝腳本將程序安裝至 %LOCALAPPDATA%\FutuCLI\bin 並添加到用户 PATH。重新打開終端後運行：

futu version

npm

需要 Node.js 18 或以上、npm 9 或以上，並能夠訪問 GitHub。通過 GitHub 安裝：

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

--install-links=true 使 npm 複製打包後的文件，避免鏈接到臨時 Git 檢出目錄。

當前 @futunn/futu-cli 尚未發佈到 npm registry，請使用上面的 GitHub 安裝命令。npm 包裝器會下載相應平台的 CLI 二進制程序。

初始化與登錄

首次使用時運行：

futu config init

該命令初始化配置並啓動 OAuth 登錄流程：

1. CLI 註冊所需的 OAuth 客户端，並打開瀏覽器授權頁面。
2. 在瀏覽器中登錄富途賬户，確認授權內容。
3. 授權完成後，通過本地回調返回 CLI，並保存 Token。

後續業務命令會複用 Token，在過期時嘗試刷新；無法刷新時，需重新登錄。

配置默認保存在 ~/.futu/config.json，Token 默認保存在 ~/.futu/token.json。需要使用其他 Token 文件時，可配置 token_file，或通過全局參數 --token-file 指定路徑。

auth login

單獨啓動登錄，或在登錄失效後重新授權：

futu auth login

已有有效 Token 時會直接複用。可通過 --client-name 設置授權客户端的識別名稱：

futu auth login --client-name "My Research Agent"

已有有效 Token 時不會因此重新發起授權；如需使用新名稱重新授權，先運行 futu auth logout。

SSH 或無圖形界面環境

在 SSH 或無圖形界面環境中，首次使用也可直接運行以下命令。CLI 會創建默認配置並註冊所需的 OAuth 客户端，無需先運行 futu config init：

futu auth login --no-browser

--no-browser 會打印授權 URL，並跳過自動打開瀏覽器。

在可用的瀏覽器中打開終端輸出的 URL 並完成授權。如果瀏覽器無法連接運行 CLI 的本地回調端口，複製瀏覽器地址欄中的完整回調 URL，粘貼回等待中的終端，再按回車完成登錄。

TIP

此方式仍需瀏覽器完成授權；無法自動回調時，再在終端粘貼完整回調 URL。

auth status

查看本地保存的 Token 狀態、過期時間、賬户信息和權限信息：

futu auth status
futu auth status --format json

該命令讀取本地狀態，不代表已驗證所有業務接口的實時權限。

auth logout

刪除本地保存的 OAuth Token：

futu auth logout

下次調用需要鑑權的命令前，需重新登錄。該命令只清除本地 Token，不向服務器發起撤銷授權請求。

首次查詢

查詢一隻股票，確認行情接口可以使用：

futu quote US.AAPL

成功後會看到包含證券代碼、交易時段、價格和漲跌的表格。以下數值僅作演示，不是實時行情：

Code	Session	Last	Change%
US.AAPL	REGULAR	180.000	+1.12%

返回了目標標的數據，即完成該次查詢驗證。數據時效和市場範圍取決於賬户權限；其他接口需要分別驗證。字段與交易時段説明見行情與市場數據。查詢失敗時查看故障排查。

連接檢查

futu check
futu check --format json

check 檢查本地 Token 及緩存權限信息，必要時嘗試刷新 Token，並測量 API 地址的 HTTP 連通性和延遲。

WARNING

check 的退出狀態不能單獨判斷 API 連通性：Token 有效但 API 不可達時，仍可能退出 0。腳本還應檢查 JSON 中的 connectivity.api.ok；HTTP 可達也不代表具體業務接口已授權。

連接或權限異常時，按授權與連接排錯繼續檢查。

配置

# 查看配置
futu config list

# 查詢指定配置項
futu config get default_account

# 設置默認證券交易賬户
futu config set default_account "替換為賬户ID"

常用配置項：

配置項	説明
api_base	REST API 地址，默認 https://webapi.futunn.com
client_id	OAuth 客户端 ID，由登錄流程註冊
redirect_uri	OAuth 本地回調地址，由登錄流程配置
token_file	OAuth Token 文件路徑
default_account	默認證券交易賬户 ID
auto_update	是否自動檢查新版本並提示，默認開啓

通常保留默認 API 地址，並由登錄流程管理客户端和回調配置即可。