linkfox-onboarding

LinkFox account and environment onboarding

Handle two types of onboarding scenarios:

1. Missing Key / Authentication failure: Not configured LINKFOX_AGENT_API_KEY, or any linkfox-* skill returns errcode=401 / authorized error → Guide the user to configure the key (scripted registration supported).
2. Insufficient billing: Any linkfox-* skill returns an insufficient billing error → Recharge process (plan → payment method → QR code).

Trigger keyword list (case-insensitive)

Conditions determined as "Missing Key / Authentication failure" (any one is sufficient):

• errcode = 401
• Error message contains authorized error、鉴权失败、未授权、unauthorized
• Environment variables LINKFOX_AGENT_API_KEY and LINKFOXAGENT_API_KEY bothare empty

Note: This skill is compatible with both key environment variable names—LINKFOX_AGENT_API_KEY(with underscore, recommended) and LINKFOXAGENT_API_KEY(without underscore, commonly used by existing customers). Other linkfox-* skills (such as linkfox-amazon-search) follow the same convention, and the same key works on both gateways.

Conditions determined as "Insufficient billing" (any one is sufficient):

• errcode = 402(Backend convention, actual test returns {"errcode": 402, "errmsg": "积分余额不足，请充值"}）
• Error message matches one of the following keywords:积分余额不足、计费不足、余额不足、quota exceeded、insufficient balance、套餐到期、需充值、请充值

Exclude:errcode = 403(No permission, not classified under these two categories).

Entry 1: Missing Key / Authentication failure onboarding

Step 1: Detect environment variables

Use Bash to run a one-line detection (Claude Code comes with a bash environment, common to all three platforms):

[ -n "$LINKFOX_AGENT_API_KEY$LINKFOXAGENT_API_KEY" ] && echo ok || echo missing

Both variable names are compatible:LINKFOX_AGENT_API_KEY(with underscore, recommended) and LINKFOXAGENT_API_KEY(without underscore, commonly used by existing customers). If either is non-empty, it is considered configured.

Step 2: Branching

Case A: Environment variables exist (authentication failure scenario)

First rule out the "just configured but did not restart" situation—this is the most common source of 401 misjudgment. Script:

It was detected that LINKFOX_AGENT_API_KEY or LINKFOXAGENT_API_KEY is configured, but authentication failed (401). Common causes:

1. Environment variables were just configured but the session was not restarted—Please first restart the terminal / Claude Code session to make the environment variables take effect, then retry the original linkfox-* skill.
2. The key is incorrect or has been reset—Go to https://agent.linkfox.com/ After logging in, go to "Personal Center → API Settings" to copy the new key. Refer to Chapter 2 of the help documentation:https://yxgb3sicy7.feishu.cn/wiki/IlkawdQP9ifKv9k22xcc7rjmnkb
3. Want to re-register with a new phone number—Tell me the phone number, and I will help you re-register and obtain a new key via SMS verification code.

Note: Both variable names are compatible (LINKFOX_AGENT_API_KEY with underscore is recommended,LINKFOXAGENT_API_KEY without underscore is the old convention), no need to rename.

After obtaining the new key, configure it according to the "Three-platform environment variable configuration examples" below, and restart the session for it to take effect.

Case B: Environment variables missing

Ask the user whether they have already registered for LinkFox Agent:

LINKFOX_AGENT_API_KEY has not been detected yet. Have you already registered for LinkFox Agent?

• Already registered / want to register yourself: Visit https://agent.linkfox.com/ to register. Registered users can log in and go to "Personal Center → API Settings" to copy the key. Refer to the help documentation:https://yxgb3sicy7.feishu.cn/wiki/IlkawdQP9ifKv9k22xcc7rjmnkb
• Want me to help you complete registration: provide your phone number (domestic phone numbers supported), and I'll help you register and get a key via SMS verification code

• User chooses to register on their own → provide the link + help documentation + the configuration example below, and the process ends.
• User provides phone number → proceed to step 3 scripted registration.

Step 3: Registration (user provides phone number)

3.1 Send verification code

Call python scripts/send_verify_code.py <phone>, the script returns JSON:

• Success:{"sent": true, "phone": "188****1234", "agreements": {"user_agreement": "...", "service_agreement": "...", "privacy_policy": "..."}}
• Failure:{"sent": false, "phone": "188****1234", "errmsg": "..."}

Note: the phone field in the script output has been masked (first 3 and last 4 retained), theagreements field contains three agreement links. Claude can directly use these two fields to display to the user, no need to read stderr.

After receiving success, output to the user (get the link from the JSON's agreements ):

The verification code has been sent to 188****1234. Replying with the verification code is deemed acceptance of the following agreements and completion of registration:

• User Agreement: <agreements.user_agreement>
• Service Agreement: <agreements.service_agreement>
• Privacy Policy: <agreements.privacy_policy>

The verification code is valid for about 5 minutes, please reply as soon as possible. If you don't want to continue, reply "cancel" to exit.

3.2 Verification code login + get key

After receiving the verification code replied by the user, call python scripts/login_and_get_key.py <phone> <code> <channel>。 Note: if you are workbuddy or the channel is workbuddy, pass workbuddy for channel, otherwise pass skill.

The script returns JSON:

• Success:{"api_key": "<token>", "phone": "188****1234", "group_id": "...", "member_id": "...", "source": "existing|generated", "is_new_user": bool, ...}
• Failure:{"error": "<阶段>: <信息>", "phone": "188****1234"}

Note:

• source field is for debugging only (existing=found an existing token, generated=newly generated), no need to explain to the user.
• Internally, the script, fornew users（is_new_user=true) will automatically call /account/loginByToken to trigger the new-user bonus points issuance, no need for Claude to intervene. Failure of this step does not block getting the key; stderr will indicate it but it continues.
• is_new_user=true , you may also inform the user "new-user points have been granted".

Failure handling：

• error contains login: 验证码错误或已过期 → prompt the user to resend the SMS (back to 3.1)
• error contains userInfo: 用户未开通任何团队空间 → guide the user to visit https://agent.linkfox.com/ to log in and complete the first activation, then retry
• error contains 团队不存在 or getApiToken/generateApiToken → guide the user to go to https://agent.linkfox.com/ , log in, enter "Personal Center → API Settings" to manually generate a key, refer to Chapter 2 of the help documentation
• Other errors → pass through the error message to the user, suggest registering on their own

3.3 Configure environment variables

After obtaining api_key , help the user configure according to the "Three-platform environment variable configuration example" below, and remind them to restart the terminal / Claude Code session to make the environment variables take effect.

Three-platform environment variable configuration example

The recommended variable name is LINKFOX_AGENT_API_KEY(with underscore, new convention). If your environment already has LINKFOXAGENT_API_KEY(without underscore, old convention) configured, it is equally valid, no need to configure again—this skill and other linkfox-* skills are compatible with both names. Same for the gateway address variable:LINKFOX_AGENT_API_URL(primary) or LINKFOX_TOOL_GATEWAY(fallback).

Windows (PowerShell, permanently write to user environment variables)：

setx LINKFOX_AGENT_API_KEY "你的key"

After configuration, restart PowerShell or the Claude Code session for it to take effect.

macOS / Linux (zsh / bash, write to shell rc)：

echo 'export LINKFOX_AGENT_API_KEY="你的key"' >> ~/.zshrc   # macOS 默认 zsh
# 或
echo 'export LINKFOX_AGENT_API_KEY="你的key"' >> ~/.bashrc  # Linux 默认 bash
source ~/.zshrc   # 或 source ~/.bashrc

Note:>> is append; run it only once for the initial configuration. Repeated execution will produce duplicate lines in the rc file (it does not affect functionality but pollutes the file; you can delete the extra lines with a text editor).

If you use the fish shell, configure the equivalent environment variables yourself.

Entry 2: Insufficient billing top-up

1. List plans: call python scripts/list_plans.py, output the JSON plan list (including plan_id、name、price、currency、credits、description、available_methods）。

2. Select a plan (validate, route by host)：

   First determine which category the current host tool belongs to:

   • Category A: hosts that support structured selection tools(Claude Code's AskUserQuestion, Gemini CLI's ask_user , etc.) → Directly use that tool to pop up an option menu. Each plan serves as one option,label shows the plan name + price (e.g. "Personal Edition ¥9.9"),description shows credits + validity period + recommended marker. After the user selects, get the corresponding plan_id。
   • Category B: hosts that only support text interaction(Codex CLI, Aider, pure command line, etc.) → Output a numbered list and let the user enter a number, for example:

     可选套餐：
     [1] 个人版 ¥9.9（100 积分，1 个月有效）
     [2] 个人版 ¥99（1200 积分，1 年有效）⭐ 推荐
     [3] 团队版 ¥999（15000 积分，1 年有效）
     请输入序号：
     

     After the user enters a number, map it to the corresponding plan_id. If the input is invalid, prompt for re-entry.

   Validate: the user's selected plan_id must exist in the list returned in the previous step; if it does not exist, prompt for re-selection.

3. Select payment method (validate, route by host)：

   From this plan's available_methods(usually ["wechat", "alipay"]), select a payment method:

   • Category A host: use the structured selection tool,wechat → "WeChat Pay",alipay → "Alipay".
   • Category B host: output a numbered list:

     支付方式：
     [1] 微信支付
     [2] 支付宝
     请输入序号：
     

   Validate: the selection must ∈ available_methods。

   Host determination hint: if in the current session you can call AskUserQuestion / ask_user and other structured selection tools, handle it as Category A; otherwise as Category B. When unsure, try Category A first, and fall back to Category B if the tool is unavailable.

4. Place order + render QR code: call python scripts/create_order.py <plan_id> <pay_method>, the script returns JSON:

   • order_id: order number (used for subsequent queries)
   • qr_content: raw QR code content (weixin:// or Alipay link, cannot be clicked directly)
   • qr_url: QR code image URL returned by the gateway (may be empty)
   • pay_url: clickable payment link (fallback)
   • png_path: locally generated PNG path
   • ascii_qr: ASCII QR code string (fallback)

5. Display to the user(by priority):

   • Preferred: use the Read tool to read png_path and display the PNG image.
   • Second choice: output pay_url for the user to click.
   • Fallback: paste ascii_qr, and honestly note "ASCII is only a fallback; it is recommended to scan the PNG or click the link first".

6. End of process: tell the user "After scanning the code and paying, you can call the original linkfox-* skill again; if the billing is still insufficient, this process will be entered again".

Payment status query (optional)

Provide python scripts/query_order.py <order_id>, returns JSON {"order_id":..., "status":..., "paid_at":...}，status ∈ paid / unpaid / expired / unknown. Can be called after the user indicates "payment completed", or combined with /loop periodic querying, but this skill does not actively poll.

Dependencies

• Python 3 (standard library urllib/json/os)
• requests: login flow HTTP calls (production WAF is sensitive to urllib),pip install requests
• QR code PNG / ASCII generation: built-in scripts/_qrgen.py(stdlib pure Python implementation, byte mode + ECC-L, bit-for-bit identical to the official qrcode library with the same version + same mask),no need to install qrcode/pillow
• Self-contained, does not depend on _shared/linkfox_paths.py

Interface contract

All endpoints (gateway /account/*、/package/*、/order/*, login flow /user/v1|v3/web/login、/account/loginByToken、/linkFoxApp/api/userCenter/userInfo、/group/getApiToken|generateApiToken) full request/response/error codes see references/api.md。

Limitations

• Only handles the two scenarios of "missing Key guidance" and "insufficient billing top-up", does not handle unsubscription, invoices, or reconciliation.
• ASCII QR code recognition rate depends on terminal font and contrast, it is recommended to prioritize PNG or pay_url。