安装与登录

完成安装、账户授权和首次查询验证。支持 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 地址，并由登录流程管理客户端和回调配置即可。