Bitget Agent Skill

bitget-agent-skill — Bitget 官方 AI 交易技能

让 Claude Code、Codex 和 OpenClaw 能够理解你的交易指令并做出判断——何时调用 Bitget、如何构建恰当的命令，以及遇到问题时该怎么办。

快速开始 · 变化内容 · 为什么需要技能 · 安装 · 安全 · 故障排除 · 常见问题

---

Bitget Agent Hub 是 Bitget 官方开源 AI Agent 生态系统。本仓库是 bitget-agent-skill——教会终端 AI Agent 何时以及如何正确调用 Bitget 工具的技能层。生态系统软件包：agent-skill（本仓库）、agent-cli、agent-mcp、agent-sdk、bitget-signal、agent_hub。

@bitget-ai/bitget-agent-skill 是 Bitget 官方 AI 交易技能文件，帮助 Claude Code、Codex 和 OpenClaw 正确使用 Bitget 工具并做出判断——了解何时调用 Bitget、如何将你的意图拆分为恰当的多步操作、如何在执行写入操作前处理确认，以及遇到问题时该怎么办。纯 Markdown，无需运行时。

适合你吗？ 如果你已经在使用 Claude Code、Codex 或 OpenClaw，并希望它真正理解你的交易指令——而不只是拥有工具却缺乏使用工具的推理能力——请安装此技能。

---

快速开始

将下面的代码块粘贴到你的 AI Agent 中——它会处理整个安装过程（需要 Node.js 20+）：

Please help me install the Bitget trading skill (requires Node.js 20+): 1. Run npx @bitget-ai/bitget-agent-skill --target all to deploy the skill files to my AI tool; 2. Run npm install -g @bitget-ai/bitget-agent-cli to install the bgc CLI globally. Tell me the result when done.

必须同时安装两者：技能文件是 AI 的操作手册，bgc 是执行工具——技能会教 AI 何时调用它以及如何构建命令，而 bgc 则实际发送 API 请求。缺少任何一者，完整流程都无法实现。

验证是否成功。 询问 AI：“Bitget 支持哪些交易模块？” 如果它返回正确的模块列表（行情、交易、账户等），说明技能已加载并处于启用状态。

---

安装后会有哪些变化

graph LR
    A[You<br/>Natural Language] --> B[Claude Code / Codex<br/>with bitget-agent-skill]
    B -->|Generates v3 Command| C[bgc CLI<br/>bitget-agent-cli]
    C -->|HMAC-SHA256 Signed| D[Bitget REST API]
    style B fill:#28a745,stroke:#333,stroke-width:2px,color:#fff

没有加载技能时，bgc 一次只执行一条命令。加载技能后，AI 可以将你的意图串联成跨模块的一系列操作——检查持仓、评估条件、下单、处理结果——一气呵成。

• 识别中英文触发语：无论你说“buy BTC at market”还是「帮我买 BTC」，AI 都能将其识别为 Bitget 交易指令，并自动调用合适的工具——无需指定命令语法
• v3 语法和完整参考：技能文件包含 bgc v3 语法（bgc <tool> --action <name>）和自动生成的全部操作目录——AI 知道哪种意图动词对应哪项操作，以及如何填写参数
• 多步骤工作流：“检查我的持仓，如果没有 BTC，就开一个 10 倍多单”——AI 会先查询、进行判断，然后下单；每次写操作前都会显示 [CAUTION]，并等待你的确认
• 模拟交易和错误处理：告诉 AI“使用演示账户”，即可自动切换到 Bitget 沙盒；发生 API 错误时，AI 知道应该重试还是向你报告问题，而不会卡住

---

为什么需要技能（而不只是安装 bgc）

单独使用 CLI，AI 可以通过统一交易账户调用 14 个意图动词（89 项操作），但缺少语义信息——助手不知道何时调用 Bitget、使用哪个动词，也不知道如何安全地操作。

技能还提供：

• 触发描述，让 Claude Code / Codex / OpenClaw 在收到任何与 Bitget 相关的请求时自动调用技能——包括随意的说法（“buy 0.1 BTC at market”）和中文（“查看我的持仓”）。
• v3 语法（bgc <tool> --action <name> --<param> <value>）和先发现再操作的工作流，以及所有动词、操作和参数的完整目录。
• 关于写操作安全（--dry-run / --confirm）、平仓方向规则、模拟交易、错误类别和身份验证设置的操作指南。

结果：你说 “buy 0.1 BTC at market on Bitget”，它就能真正执行——助手会组合出 bgc order --action place --category SPOT --symbol BTCUSDT --side buy --orderType market --qty 0.1，用 --dry-run 预览，与你确认后再执行。

---

技能包含的内容

文件	用途
SKILL.md	顶层技能定义，包含中英文触发短语，让 AI 知道何时调用技能；还包括 v3 语法、14 个动词的映射以及写操作安全工作流。
references/commands.md	自动生成的静态目录——包含 SDK 自带的 discover 接口中的所有领域、动词、操作和参数（包括枚举值和说明）。
references/discover-guide.md	如何使用 bgc discover 浏览实时接口（四个层级、搜索、raw）。
references/trading-safety.md	平仓方向规则（单向/对冲）、TP/SL、qty 单位、全部撤单和提现安全。
references/auth-setup.md	如何创建 Bitget API 密钥并配置环境变量。
references/demo-trading.md	如何使用 --paper-trading 进行安全演练。
references/error-codes.md	v3 错误载荷、按类别进行恢复，以及整理后的 Bitget 错误码表。

---

安装

步骤 1：安装 CLI

npm install -g @bitget-ai/bitget-agent-cli

为什么使用 -g？bgc 是一个持久运行的 CLI，你的 AI 每个会话会调用数十次——它必须位于 $PATH 中。相比之下，此技能只需部署一次：npx 会将 Markdown 复制到 AI 工具的技能目录，然后退出。npx 始终获取最新版本，因此后续运行时会自动升级。

步骤 2：部署技能文件

# Default — Claude Code only
npx @bitget-ai/bitget-agent-skill

# All supported AI tools
npx @bitget-ai/bitget-agent-skill --target all

# Choose interactively
npx @bitget-ai/bitget-agent-skill --interactive

--target all 会同时部署到 Claude Code、Codex 和 OpenClaw。

目标	技能位置
Claude Code	~/.claude/skills/bitget-agent-skill/
Codex	~/.codex/skills/bitget-agent-skill/
OpenClaw	~/.openclaw/skills/bitget-agent-skill/

Step 3：设置凭据

export BITGET_API_KEY="your-api-key"
export BITGET_SECRET_KEY="your-secret-key"
export BITGET_PASSPHRASE="your-passphrase"

如果还没有 API 密钥，请创建 API 密钥。如需进行模拟交易，请改用 Demo API 密钥：

export BITGET_DEMO_API_KEY="your-demo-key"
export BITGET_DEMO_SECRET_KEY="your-demo-secret"
export BITGET_DEMO_PASSPHRASE="your-demo-passphrase"

Step 4：重启并验证

关闭并重新打开 AI 工具，然后询问："你具备哪些 Bitget 交易能力？"

---

相关工具

工具	关系
@bitget-ai/bitget-agent-cli	必须一同安装：bgc 是执行工具，技能文件是 AI 的操作手册——缺一不可
@bitget-ai/bitget-agent-mcp	桌面 AI（Claude Desktop、Cursor）的替代方案——无需 bgc
@bitget-ai/bitget-signal	市场分析技能——无需 API 密钥。此技能负责交易执行；bitget-signal 负责市场分析。二者互为补充，可并行安装

---

安全性

技能文件本身：

• 无需 API 密钥——纯 Markdown 文件
• 无网络访问——无运行时进程
• 不存储凭据——密钥通过环境变量传递给 bgc

所有实际 API 调用均通过 bgc 进行，它提供：

• 凭据仅存在于环境变量中（不解析 .env 文件）
• --read-only 会移除所有写入工具
• --paper-trading 会切换到模拟环境
• 本地 HMAC-SHA256 请求签名

---

故障排除

“AI 无法识别技能”

原因： 技能文件尚未部署，或 AI 工具尚未重启。

解决方法：

1. 重新部署：npx @bitget-ai/bitget-agent-skill --target all
2. 完全重启 AI 工具
3. 验证：询问 “有哪些 Bitget 交易模块可用？”

“AI 可以使用 bgc，但不理解交易命令”

原因： 缺少技能文件——虽然已安装 bgc，但 AI 没有操作手册。

解决方法： 部署技能，并确认文件位于正确位置：

AI 工具	预期位置
Claude Code	~/.claude/skills/bitget-agent-skill/SKILL.md
Codex	~/.codex/skills/bitget-agent-skill/SKILL.md
OpenClaw	~/.openclaw/skills/bitget-agent-skill/SKILL.md

“bgc：找不到命令”

原因： 尚未安装 bitget-agent-cli，或它不在 $PATH 中。

解决方法： 运行 npm install -g @bitget-ai/bitget-agent-cli，然后重启终端。

---

更新

# Update all Bitget AI packages
npx @bitget-ai/bitget-agent-installer upgrade-all --target all

# Or update just this skill
npx @bitget-ai/bitget-agent-skill@latest

---

常见问题

安装技能后，AI 会自动下单吗？ 不会。对于下单或转账等写入操作，AI 会显示 [CAUTION] 注释，并在执行前等待你确认。

如何不使用真实资金进行交易？ 告诉 AI“使用模拟账户”或“使用模拟交易”——它会自动切换到 Bitget 的模拟交易环境。需要 Demo API 密钥。

这与 MCP 服务有什么区别？ 终端 AI（Claude Code、Codex）→ 安装 bitget-agent-skill + bgc。桌面 AI（Claude Desktop、Cursor）→ 安装 bitget-agent-mcp。两者都支持通过自然语言进行 Bitget 交易，分别适配不同的 AI 环境。

技能文件是否需要 API 密钥或网络访问？ 不需要。它是纯 Markdown 文件，没有运行时进程。所有 API 调用都通过 bgc 在执行时进行。

它免费吗？ 采用 MIT 许可证，可免费使用。

---

贡献

• 错误报告和功能请求： GitHub Issues
• 讨论： GitHub Discussions
• 安全问题： [email protected]

---

许可证

MIT — 可免费用于个人和商业用途。

---

_{属于 Bitget 的官方开源 AI Agent 生态系统 Bitget Agent Hub 生态的一部分。
交易栈 · 技能层。⚠️ 加密货币交易存在风险；您需对 AI Agent 下达的任何订单负责。使用真实资金交易前，请先通过模拟账户安全练习。
基础： agent-sdk · 执行： agent-cli · 桌面端： agent-mcp · 市场信号： bitget-signal}