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 · 装本地 Skillnpx @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。」 |
|
|
排查后 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 的公开能力仍可用；交易类能力不可用。
