Bitget Agentic 账户 连接指南

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

Agent 要做什么： 读取本文后，按 Step 0–5 依次执行：安装本地 Skill 与 MCP → 调用 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），工具才会出现。若调用报"工具不存在"，先检查注册与重连，再查 MCP 是否运行，不要误判为授权问题。



Step 2 · 触发 OAuth

必须调 MCP 授权 tool authorize_start，禁止 LLM 拼 URL / 监听 callback。

调用后授权 tool 返回授权链接（data.authorizeUrl 字段）与 sessionId。若浏览器未自动打开，Agent 必须手动打开，不等用户复制粘贴：

• macOS: open "<authorizeUrl>"

• Linux: xdg-open "<authorizeUrl>"

• Windows: start "" "<authorizeUrl>"

• 打开失败（无 GUI/无浏览器/命令不存在）才把链接文本发给用户自行打开。链接原样使用授权 tool 返回值，禁止自行拼接或修改。

拿回什么： 用户在浏览器完成授权后，MCP/SDK 通过回调接收并本地保存凭证（见 Step 5）。Agent 需确认已授权才算完成：调用 authorize_wait（传入 authorize_start 返回的 sessionId）等待返回，或调用 get_auth_status 确认状态为已授权。

提示：

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


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 安装并注册后重试。」

兜底（无明确错误码）： 通用失败 / 超时 / 回调未收到 / 浏览器状态不确定时，Agent 无法知道具体原因（取消、没点完、页面关了等），不猜原因，统一提示「授权未完成」并重新走一遍授权流程：

「授权未完成。请确认浏览器授权步骤已完成，要我再发起一次吗？」



禁止： 让用户手动创建 Key 粘贴 · 承诺一键重发 · 未完成 OAuth 就交易 · 无法确认失败原因时猜测归因

未授权能力： 未授权时行情等无需 Key 的公开能力仍可用；交易类能力不可用。