Bitget Agentic 账户连接指南

2026-09-03 08:380641

本文是什么： Bitget Agentic 首次接入指南（在线文档）。把它交给 AI Agent 后，Agent 会引导你完成「安装 Skill + MCP → 浏览器 OAuth 授权 → 自动生成凭证」的首次连接，全程不需要你手动创建或复制 API Key。

Agent 要做什么： 读取本文后，按 Step 0–5 依次执行：安装本地 Skill 与 MCP → 本会话若刚完成首次 MCP 注册，先按 Step 1 重启会话，不要在本会话调授权 tool → 新会话调用 MCP 授权 tool 触发 OAuth → 等待用户在浏览器完成授权 → 确认 MCP 已保存凭证 → 给出完成提示。你不要让用户手动创建或粘贴 Key，也不要自行拼 OAuth URL 或监听回调。

之后： 首次授权完成后本文使命结束；后续 Key 失效、重新授权、交易与风控由本地 bitget-agentic skill 处理（npx @bitget-ai/bitget-agent-skill --skill agentic）。

Step 0 · 装本地 Skill

npx @bitget-ai/bitget-agent-skill --target all --skill agentic # 默认安装到全部支持的客户端（cursor / claude / codex）

若你的客户端不在默认列表，用 --target <客户端> 指定，或按客户端要求手动放置 skill 文件到对应目录。
必须带 --skill agentic；不带该参数默认只装 UTA（手填 Key）skill。

Step 1 · 装 MCP

前置： Node 20+（node -v 确认）。

安装（全局）：

npm i -g @bitget-ai/bitget-agent-mcp

配置约束：

不要配置 BITGET_API_* 环境变量（凭证由 OAuth 回调落盘，不走 env）
MCP 使用 stdio 协议，注册进客户端时的启动命令为：npx -y @bitget-ai/bitget-agent-mcp（见下方「客户端差异 · MCP 注册」）

客户端差异 · MCP 注册

MCP 需注册进当前客户端后 Agent 才能调用其 tool。由 Agent 检测自身所在客户端并执行对应注册：

Claude Code： claude mcp add bitget-agentic -- npx -y @bitget-ai/bitget-agent-mcp（或改 ~/.claude.json / 项目 .mcp.json）
Cursor： 在 Cursor 设置 → MCP 中新增 stdio server，command 填 npx -y @bitget-ai/bitget-agent-mcp
其他客户端： Agent 按当前客户端的 MCP 注册方式自行注册一个 stdio server，command 填 npx -y @bitget-ai/bitget-agent-mcp

注册后必须重启会话或用客户端 MCP 重连（如 Claude Code 的 /mcp），工具才会出现在当前会话。健康检查 Connected / claude mcp list 显示已连接，只说明 server 能跑，不等于本会话已能调用 authorize_start。

首次注册后：停在这里，重启会话再授权

本会话刚装上并注册 MCP 时，不要进入 Step 2。 新注册的 MCP 对当前会话通常不可见；此时调 authorize_start 会报 tool 不存在 / server not found。这是会话未重载，不是授权失败，不要猜原因、不要改拼 OAuth URL。

Agent 必须：

向用户说明：Step 0–1 已完成，但授权 tool 要等新会话加载 MCP 后才能调用。
给出下面固定提示词（MCP 启动命令填你刚才注册的那条；不知道就填 npx -y @bitget-ai/bitget-agent-mcp），请用户复制到新会话发送。
按客户端告诉用户怎么重启：Claude Code 退出当前会话并重新运行 claude；Cursor 新开一个 Agent 对话；其他客户端重启会话或 MCP 重连。
到此停止。 不要在本会话继续 OAuth。

给新会话的提示词（请复制）：

我已装好 bitget-agentic skill 和 MCP（npx -y @bitget-ai/bitget-agent-mcp）。请继续 Bitget Agentic 账户授权：调用 authorize_start 触发 OAuth，打开浏览器等我在页面完成登录/选户/Allow/设备鉴权，然后用 get_auth_status 确认授权完成。

请退出当前会话并重新开始，把上面那段话发给新会话即可继续。

若调用报「工具不存在」：先确认是否已按上面重启/重连，再查 MCP 是否运行，不要误判为授权问题。

Step 2 · 触发 OAuth

按 2.1 → 2.6 顺序执行，每步做完再做下一步。

2.1 前置门：本会话工具列表里有 authorize_start 吗

没有 → 不要调用、不要拼 URL、不要往下走。执行上面 Step 1「首次注册后」的四步（说明现状 → 给固定提示词 → 告知怎么重启 → 停止本会话流程）。
有 → 进入 2.2。

2.2 调 authorize_start

必须由这个 tool 产生授权链接。禁止 LLM 自己拼 URL、自己起本地服务监听 callback。

调用前先定 authorizeBaseUrl（域名必须跟用户当前这条提示语里的 URL 域名一致）：

看用户当前这条消息里有没有 URL（例如「请阅读【https://www.bitget.cloud/...】并帮我完成...」）。
有 URL → 取该 URL 的协议 + 域名（如 https://www.bitget.cloud），作为参数 authorizeBaseUrl 传给 authorize_start。不要猜地区、不要换别的域名。
没有 URL → 不传 authorizeBaseUrl，走 SDK 默认域名。

调用失败 → 转「首次 OAuth 失败」章节按错误码处理，不要继续 2.3。

2.3 从返回值取两个字段

字段	用途
`data.authorizeUrl`	要打开的授权链接，原样使用，禁止拼接或修改
`sessionId`	2.5 传给 `authorize_wait`

2.4 打开浏览器

浏览器没自动打开时，Agent 自己执行命令打开，不要等用户复制粘贴：

macOS: open "<authorizeUrl>"
Linux: xdg-open "<authorizeUrl>"
Windows: start "" "<authorizeUrl>"

只有命令执行失败（无 GUI / 无浏览器 / 命令不存在）时，才把链接文本发给用户自行打开。

同时发这句给用户：

即将打开浏览器完成 Agentic 账户授权：登录 → 选 Create new 或 Use existing → Allow → Bitget App 设备鉴权 → Use existing 须填 Key 备注。无需复制 API Key。

2.5 等待授权结果

用户在浏览器完成授权后，MCP/SDK 通过回调接收并本地保存凭证（见 Step 5）。Agent 二选一确认：

调 authorize_wait，传入 2.3 拿到的 sessionId，等它返回；或
调 get_auth_status，确认状态为已授权。

2.6 判定

已授权 → 进入 Step 5。
未授权 / 超时 / 报错 → 转「首次 OAuth 失败」章节。不要因为浏览器页面看起来完成了就当成功。

Step 3–4 · 浏览器（用户操作，Agent 等待）

Step 3： 登录；KYC 未完成 → 站内完成后再 OAuth（Case L）
Step 4： Create new 或 Use existing → App 设备鉴权
- Create new：创建新的 Agentic 账户
- Use existing：选择已有 Agentic 账户，须填 Key 备注
- 不含 Playbook · 再授权 = 新 Key、旧 Key 保留（再次授权会更新本机凭证，Web 上旧 Key 默认保留）
- 选户由 OAuth 前端完成，Agent 只负责触发授权并等待结果

Step 5 · 成功

MCP 本地落盘三件套 + 浏览器到资产页。调 get_auth_status = 已授权。

三件套 = API Key、Secret Key、Passphrase；由 MCP/SDK 在回调侧接收并本地保存；Web 不存；用户无需复制或粘贴。
成功判定：只有 MCP 确认凭证已保存且授权状态成功，才算完成；浏览器页面完成不作为成功依据。

提示：

首次授权完成。之后如果 Key 失效或你说「重新授权」，我会重新打开 OAuth。若要取消这个 Agent 的交易权限，请在 Bitget 网页端中删除该 Agentic 账户对应的 API Key；删除 Key 不会自动平仓或撤销挂单。接下来请你手动从 Bitget 主账户向 Agentic 账户转入一笔你愿意承担的小额资金，到账后先对我说「查看 Agentic 账户余额」，再尝试交易。转账和主账户操作由你自己完成；我不会操作你的主账户，只能操作已授权的 Agentic 账户。实际可交易资产以账户当前开放范围为准。

不要让用户粘贴 Key。此后交给本地 Skill。 若本会话未加载 bitget-agentic skill（skill 列表在会话启动时扫描，本会话内新装的 skill 可能不可用），提示用户新起一个对话再继续——新会话会自动加载该 skill，Agent 才有其运行时规则。

首次 OAuth 失败（仅 Guide）

只按错误码归因： 授权 tool 返回明确错误码时按错误码处理；无明确错误码时一律兜底，不猜原因，重新走授权流程。

错误码 → 动作：

错误码	动作	提示
配额错误码（K 配额满）	Use existing	「请改选 Use existing。」
KYC 错误码（L KYC 未完成）	完成后再 OAuth	「请先完成 KYC。」
`MCP_CONNECTION_ERROR`（M MCP 未运行）	排查后 OAuth	「请检查 Node 20+、MCP 配置，终端跑 npx @bitget-ai/bitget-agent-mcp。」
工具不存在 / 方法不存在（M2 MCP 未安装/未注册）	引导安装注册后重试	「MCP 工具不存在：请运行 npm i -g @bitget-ai/bitget-agent-mcp 安装并注册后重试。」