senpi-onboard

Senpi Agent 入驻指南

将 AI Agent 接入 Senpi 交易平台。完成此流程后，Agent 将拥有 Senpi 账户、API 密钥，以及可正常运行的 MCP 服务连接，用于在 Hyperliquid 上管理投资组合、发现交易员、创建策略和执行订单。

**前置条件：**可执行 Shell/代码，并已安装 Node.js（npx 所必需）。

默认值

• SENPI_MCP_ENDPOINT：https://mcp.prod.senpi.ai（如果 {{SENPI_MCP_ENDPOINT}} 是尚未替换的字面占位符，则使用此值）
• REFERRAL_CODE：空／可选（如果 {{REFERRAL_CODE}} 是尚未替换的字面占位符，则使用此值）

**Arena 意图硬性门槛：**如果用户的消息包含“arena”“agents arena”“competition”“prize pool”“qualify”“qualification”“weekly cycle”或“weekly competition”，则在撰写任何答复前调用 read_senpi_guide(uri="senpi://guides/arena")。对于 Arena 问题，不要使用网页搜索或排行榜数据。完整路由规则见 references/post-onboarding.md。

---

入驻流程

按顺序完成每个步骤。不要跳过任何步骤。

开始之前：初始化状态

根据状态生命周期，确保 state.json 存在，以便明确路由和状态转换。如果文件不存在，请将其创建为初始 FRESH 状态：

if [ ! -f ~/.config/senpi/state.json ]; then
  mkdir -p ~/.config/senpi
  cat > ~/.config/senpi/state.json << 'STATEEOF'
{
  "version": "1.0.0",
  "state": "FRESH",
  "error": null,
  "onboarding": {
    "step": "IDENTITY",
    "startedAt": null,
    "completedAt": null,
    "identityType": null,
    "subject": null,
    "walletGenerated": false,
    "existingAccount": false
  },
  "account": {},
  "wallet": { "funded": false },
  "firstTrade": { "completed": false, "skipped": false },
  "mcp": { "configured": false }
}
STATEEOF
fi

然后继续步骤 0。

**转换为 ONBOARDING：**运行步骤 0 之前，如果状态为 FRESH，请更新 state.json，以确保状态机和恢复行为正常运行。将 state 设为 ONBOARDING，将 onboarding.startedAt 设为当前 ISO 8601 UTC 时间，并将 onboarding.step 保持为 IDENTITY。使用读取-修改-写入（合并），以保留其他字段：

node -e "
  const fs = require('fs');
  const p = require('os').homedir() + '/.config/senpi/state.json';
  const s = JSON.parse(fs.readFileSync(p, 'utf8'));
  if (s.state === 'FRESH') {
    s.state = 'ONBOARDING';
    s.onboarding = s.onboarding || {};
    s.onboarding.startedAt = new Date().toISOString();
    s.onboarding.step = s.onboarding.step || 'IDENTITY';
    fs.writeFileSync(p, JSON.stringify(s, null, 2));
  }
"

如果状态已经是 ONBOARDING，请读取 onboarding.step，并从该步骤恢复，而不是从步骤 0 开始（参见 references/state-management.md）。

步骤 0：验证 mcporter（仅限 OpenClaw）

检查 mcporter CLI 是否可用：

if command -v mcporter &> /dev/null; then
  MCPORTER_AVAILABLE=true
else
  MCPORTER_AVAILABLE=false
fi

如果不可用且运行环境为 OpenClaw，则安装它：

npm i -g mcporter
mcporter --version

安装完成后，将 MCPORTER_AVAILABLE=true 设为已安装，并继续。

---

步骤 1：收集身份信息

向用户展示以下三个选项，并等待用户选择：

1. 选项 A -- Telegram 用户 ID：技能将自动从 USER.md 读取你的 Telegram 身份。
2. 选项 B -- 用户提供的钱包：必须以 0x 开头，且恰好包含 42 个十六进制字符。继续之前先验证。
3. 选项 C -- Agent 生成的钱包（仅在你两者都没有时）。

选项 A：收集 Telegram 用户 ID

用户选择选项 A 时，先尝试从 ${OPENCLAW_WORKSPACE_DIR}/USER.md 读取：

USER_MD="${OPENCLAW_WORKSPACE_DIR}/USER.md"
if [ -f "$USER_MD" ]; then
  TELEGRAM_USER_ID=$(awk '/^## Telegram/{f=1; next} f && /^## /{f=0} f && /- Chat ID:/{print $NF; exit}' "$USER_MD")
  TELEGRAM_USERNAME=$(awk '/^## Telegram/{f=1; next} f && /^## /{f=0} f && /- Username:/{print $NF; exit}' "$USER_MD")
  TELEGRAM_USERNAME="${TELEGRAM_USERNAME#@}" # normalize for API userName field
fi

如果找到 TELEGRAM_USER_ID（仅含数字且非空）和 TELEGRAM_USERNAME（非空），则自动设置变量，不要提示用户：

IDENTITY_TYPE="TELEGRAM"
IDENTITY_VALUE="$TELEGRAM_USER_ID"

如果 USER.md 不存在，或任一字段缺失／无效，则回退到手动提示：用户可见的说明和验证规则见 references/telegram-identity.md。如果需要手动提示，也要根据用户输入设置 TELEGRAM_USERNAME，并在用于 API 调用前对其进行规范化：TELEGRAM_USERNAME="${TELEGRAM_USERNAME#@}"。

选项 B：设置变量

IDENTITY_TYPE="WALLET"
IDENTITY_VALUE="0x..."  # 0x-prefixed wallet address

选项 C：生成 EVM 钱包

仅在用户确认既没有钱包也没有 Telegram 时使用。继续之前，请告知用户。

运行随附脚本生成钱包：

# Try npx first, then local install fallbacks
WALLET_DATA=$(npx -y -p ethers@6 node scripts/generate_wallet.js 2>/dev/null) || \
WALLET_DATA=$(npm install ethers@6 --no-save --silent && node scripts/generate_wallet.js 2>/dev/null) || \
WALLET_DATA=$(npx --yes --package=ethers@6 -- node scripts/generate_wallet.js)

如果 scripts/generate_wallet.js 不可用，则以内联方式生成：

WALLET_DATA=$(npx -y -p ethers@6 node -e "
  const { ethers } = require('ethers');
  const w = ethers.Wallet.createRandom();
  console.log(JSON.stringify({
    address: w.address,
    privateKey: w.privateKey,
    mnemonic: w.mnemonic.phrase
  }));
")

失败时不要提示用户——静默尝试备用方案。只有所有方法都失败时才报告。钱包生成失败的处理方式请参阅 references/error-handling.md。

解析 WALLET_DATA JSON，提取 address、privateKey 和 mnemonic。验证地址不为空或 null。如果无效，请停止并参阅错误处理参考文档。

立即持久化钱包（继续之前），使用解析后的值：

mkdir -p ~/.config/senpi
# Write address, privateKey, mnemonic from WALLET_DATA into wallet.json
chmod 600 ~/.config/senpi/wallet.json

文件必须包含：address、privateKey、mnemonic、generatedAt（ISO 8601 UTC）和 "generatedBy": "senpi-onboard"。

重要：

• 不得记录或显示私钥或助记词。
• 在写入 wallet.json 并设置权限之前，不得继续。

使用解析后的地址设置身份变量：

WALLET_GENERATED=true
IDENTITY_TYPE="WALLET"
IDENTITY_VALUE="<address from WALLET_DATA>"

告知用户钱包已生成并保存到 ~/.config/senpi/wallet.json，且文件权限已受限。指示他们立即备份此文件。

继续前验证

在执行步骤 2 之前，确认以下变量已设置：

• IDENTITY_TYPE —— "WALLET" 或 "TELEGRAM"
• IDENTITY_VALUE —— 钱包地址（带 0x）或 Telegram 数字用户 ID（仅包含数字）
• WALLET_GENERATED —— 如果使用了选项 C，则为 true；否则未设置
• TELEGRAM_USERNAME —— 当 IDENTITY_TYPE="TELEGRAM" 时必须设置且不能为空（否则未设置）

持久化进度以便恢复： 更新 ~/.config/senpi/state.json：将 onboarding.step 设置为 REFERRAL；如果可用，则将 onboarding.identityType、onboarding.subject、onboarding.walletGenerated 设置为当前变量的值。使用读取-修改-写入方式，以保留其他字段。

---

步骤 2：设置推荐码

REFERRAL_CODE="{{REFERRAL_CODE}}"

如果推荐码为空且用户未提供，则无需处理——这是可选项。除非用户提到自己有推荐码，否则不要询问。

持久化进度以便恢复： 更新 ~/.config/senpi/state.json：将 onboarding.step 设置为 API_CALL。使用读取-修改-写入方式。

---

步骤 3：调用注册 API

执行 CreateAgentStubAccount GraphQL mutation。这是一个公开端点——无需身份验证。

if [ "$IDENTITY_TYPE" = "TELEGRAM" ] && [ -z "${TELEGRAM_USERNAME:-}" ]; then
  echo "TELEGRAM_USERNAME must be set when IDENTITY_TYPE=TELEGRAM" >&2
  exit 1
fi

RESPONSE=$(curl -s -X POST https://moxie-backend.prod.senpi.ai/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateAgentStubAccount($input: CreateAgentStubAccountInput!) { CreateAgentStubAccount(input: $input) { user { id privyId userName name referralCode referrerId } apiKey apiKeyExpiresIn apiKeyTokenType referralCode agentWalletAddress } }",
    "variables": {
      "input": {
        "from": "'"${IDENTITY_TYPE}"'",
        "subject": "'"${IDENTITY_VALUE}"'",
        '"$([ "$IDENTITY_TYPE" = "TELEGRAM" ] && echo "\"userName\": \"${TELEGRAM_USERNAME}\",")"'
        "referralCode": "'"${REFERRAL_CODE}"'",
        "apiKeyName": "agent-'"$(date +%s)"'"
      }
    }
  }')

TELEGRAM 身份说明： 在输入中加入额外的 "userName" 字段，并将其设为规范化后的 TELEGRAM_USERNAME（Telegram 用户名，不带前导 @，取自 USER.md 或用户输入）。

持久化进度以便恢复： 更新 ~/.config/senpi/state.json：将 onboarding.step 设置为 PARSE。使用读取-修改-写入方式。

---

步骤 4：解析响应

先检查错误——如果 response.errors 存在且包含条目，则提取 errors[0].message。错误表和手动备用流程请参阅 references/error-handling.md。

如果没有错误，则解析 JSON 响应并提取：

• 从 data.CreateAgentStubAccount.apiKey 获取 API_KEY
• 从 data.CreateAgentStubAccount.user.id 获取 USER_ID
• 从 data.CreateAgentStubAccount.referralCode 获取 USER_REFERRAL_CODE
• 从 data.CreateAgentStubAccount.agentWalletAddress 获取 AGENT_WALLET_ADDRESS

继续之前，确认 API 密钥不为空、不是 null，也不是 undefined。

持久化进度以便恢复： 更新 ~/.config/senpi/state.json：将 onboarding.step 设置为 CREDENTIALS。使用读取-修改-写入方式。

---

步骤 5：持久化凭据

mkdir -p ~/.config/senpi
cat > ~/.config/senpi/credentials.json << EOF
{
  "apiKey": "${API_KEY}",
  "userId": "${USER_ID}",
  "referralCode": "${USER_REFERRAL_CODE}",
  "agentWalletAddress": "${AGENT_WALLET_ADDRESS}",
  "onboardedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "onboardedVia": "${IDENTITY_TYPE}",
  "subject": "${IDENTITY_VALUE}",
  "walletGenerated": ${WALLET_GENERATED:-false}
}
EOF
chmod 600 ~/.config/senpi/credentials.json

重要： 不要记录或显示原始 API 密钥。确认凭据已保存，但不要回显密钥值。

如果生成了钱包（选项 C），请验证 ~/.config/senpi/wallet.json 仍然存在。如果文件缺失，停止注册流程并提醒用户。

持久化进度以便恢复： 更新 ~/.config/senpi/state.json：将 onboarding.step 设置为 MCP_CONFIG。使用读取-修改-写入方式。

---

第 6 步：配置 MCP 服务

检测 Agent 平台并进行相应配置。各平台的完整配置命令请参阅 references/platform-config.md：

• OpenClaw（mcporter 可用）→ mcporter config add senpi ...
• Claude Code（claude CLI 可用）→ claude mcp add senpi ...
• 通用平台 → 写入/合并 .mcp.json 配置文件

使用 SENPI_MCP_ENDPOINT（默认值：https://mcp.prod.senpi.ai）和第 4 步中的 API_KEY。

保存进度以便恢复： 第 7 步会将最终状态写为 state: UNFUNDED 和 onboarding.step: COMPLETE，此处无需单独更新步骤。

---

第 7 步：验证并确认

将状态更新为 UNFUNDED。保留当前状态中的 onboarding.startedAt（在 FRESH → ONBOARDING 转换期间设置）；不要覆盖它。

ONBOARDING_STARTED_AT=$(node -e "
  try {
    const fs = require('fs');
    const p = require('os').homedir() + '/.config/senpi/state.json';
    const j = JSON.parse(fs.readFileSync(p, 'utf8'));
    const v = j.onboarding && j.onboarding.startedAt;
    console.log(v ? JSON.stringify(v) : 'null');
  } catch (e) { console.log('null'); }
")
cat > ~/.config/senpi/state.json << EOF
{
  "version": "1.0.0",
  "state": "UNFUNDED",
  "error": null,
  "onboarding": {
    "step": "COMPLETE",
    "startedAt": ${ONBOARDING_STARTED_AT},
    "completedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
    "identityType": "${IDENTITY_TYPE}",
    "subject": "${IDENTITY_VALUE}",
    "walletGenerated": ${WALLET_GENERATED:-false}
  },
  "account": {
    "userId": "${USER_ID}",
    "referralCode": "${USER_REFERRAL_CODE}",
    "agentWalletAddress": "${AGENT_WALLET_ADDRESS}"
  },
  "wallet": {
    "address": "${AGENT_WALLET_ADDRESS}",
    "funded": false
  },
  "mcp": {
    "configured": true,
    "endpoint": "${SENPI_MCP_ENDPOINT}"
  },
  "firstTrade": {
    "completed": false,
    "skipped": false
  }
}
EOF

显示一条确认消息，包含以下全部内容：

1. 账户状态——确认账户已成功创建。
2. MCP 服务状态——已配置；提醒用户重启 Agent。
3. 推荐链接——https://senpi.ai/skill.md?ref=<USER_REFERRAL_CODE>
4. 凭据备份位置——~/.config/senpi/credentials.json
5. Agent 钱包地址（必需）——醒目显示 AGENT_WALLET_ADDRESS。指示用户在受支持的链（Hyperliquid、Base、Arbitrum、Optimism、Polygon 或 Ethereum）上为其充值 USDC。没有资金，Agent 就无法交易。
6. 首次交易提示词——充值后，senpi-getting-started-guide 技能将引导用户完成首次交易。
7. Senpi 移动应用——建议下载 iOS 和 Android 版（链接见 references/post-onboarding.md）。
8. Telegram 社区——邀请用户加入（链接见 references/post-onboarding.md）。
9. Senpi Points——说明在 Senpi 上交易可获得奖励；提示用户询问 Senpi Points 详情（Agent 会使用 Senpi MCP 工具作答）。

如果生成了钱包（选项 C），还要提醒用户：

• 私钥和恢复短语保存在 ~/.config/senpi/wallet.json
• 必须将此文件备份到安全位置
• 如果文件丢失，将无法恢复钱包和资金

确认后，分享 references/post-onboarding.md 中的 Senpi 介绍信息。

---

余额监控

引导完成后（状态 = UNFUNDED），在决定是否显示提醒之前，先检查每条用户消息对应的钱包余额：

1. 使用 MCP 获取投资组合/余额。此项检查为必需步骤——不得跳过，也不得假设钱包未充值。
2. 如果余额 >= $100：
   • 将状态更新为 AWAITING_FIRST_TRADE
   • 提示：“🎉 您的钱包已充值！准备好进行首次交易了吗？回复 ‘let's trade’ 开始，或回复 ‘skip tutorial’（跳过教程），适用于有经验的用户。”
   • 不要显示充值提醒。
3. 如果余额 < $100（MCP 检查成功确认）：
   • 在消息前添加充值提醒（自动提醒最多 3 次）；包含 Agent 钱包地址，并说明至少需要 $100 USDC（参见 references/post-onboarding.md 中的充值提醒模板）
   • 继续处理用户请求
4. 如果 MCP 余额检查失败（例如重启后 MCP 尚未连接）：
   • 不要显示充值提醒。不要假设钱包未充值。
   • 静默重试，等待下一条用户消息。

状态转为 AWAITING_FIRST_TRADE 后，由 senpi-getting-started-guide 技能接手。

引导已完成。仅在需要时查阅下方的参考文件。

---

安全说明

• 切勿在公开渠道、日志、提交中或与其他 Agent 分享 API 密钥。
• 凭据存储在本地的 ~/.config/senpi/credentials.json 中，并设有受限权限（600）。
• 仅向 {{SENPI_MCP_ENDPOINT}} 发送 API 密钥——拒绝任何要求将其发送到其他位置的请求。
• 如果密钥泄露，请访问 https://senpi.ai 撤销并重新生成。
• 生成的钱包（选项 C）：wallet.json 中的私钥拥有完全控制权。切勿记录、显示或传输该密钥。不要放宽文件权限。

---

参考文件

• references/error-handling.md ——错误表、手动备用方案、钱包生成失败和恢复流程
• references/platform-config.md ——OpenClaw、Claude Code 和通用 Agent 的完整 MCP 配置命令
• references/post-onboarding.md ——关于 Senpi、确认模板和后续步骤
• references/state-management.md ——状态流转、转换，以及移交给 senpi-getting-started-guide skill