kalopilot

KaloPilot — TikTok Eコマースデータアシスタント

このスキルを使うと、KaloPilot AI エージェントを通じて TikTok Shop のデータを照会できます。KaloPilot は、すべての TikTok Shop 地域において、商品、ショップ、クリエイター、動画、ライブ配信、カテゴリーを対象とする 20 種類以上の専門ツールを利用できます。

認証

トークンは ~/.kalopilot/token にプレーンテキストで保存されます。初回使用時にトークンがない場合、最初のリクエストは明確なエラーとともに失敗します。これは想定どおりの動作です。

トークンがない場合は、「トークンが必要です」と伝えるだけで済ませず、取得方法をユーザーに案内してください。

1. kalodata.com/pilot にアクセスしてログインします。
2. サイドバーの左下にある Connect OpenClaw（「スキルのインストールチュートリアル」）をクリックします。
3. 表示される OpenClaw Integration Guide ダイアログで、Current Account Token の下にある文字列をコピーします。これは 89e7f60c...5be6b9 のような長い 16 進数の文字列です。
4. ここに貼り付けてもらい、こちらで保存します。

ユーザーがトークンを送信したら、保存してください（ディレクトリも作成され、アクセス権限が制限されます）。

mkdir -p ~/.kalopilot && echo -n "<token>" > ~/.kalopilot/token && chmod 600 ~/.kalopilot/token

保存したことを確認し、すぐに元の質問を再試行してください。ユーザーにもう一度依頼させないでください。

プロンプトを表示する前に、トークンがすでに設定されているか確認するには、次のコマンドを実行します。

[ -s ~/.kalopilot/token ] && echo "configured" || echo "missing"

ユーザーから認証エラー（401／無効なトークン）の報告があった場合、保存済みのトークンが古くなっている可能性があります。同じ手順で新しい Current Account Token を取得し、上記のコマンドでファイルを上書きするよう案内してください。

API エンドポイント

このスキルでは、非同期の送信＋ポーリング方式を使用します。送信すると、すぐに task_id が返されます。その後、サーバー上でエージェントの処理が完了するまで実行されます。短いリクエストで結果をポーリングするため、接続が開いたままになることはなく、分析にどれだけ時間がかかっても、ゲートウェイのアイドルタイムアウトは発生しません。

POST https://www.kalodata.com/api/pilot/skill/ext/v1/chat/async/submit
GET  https://www.kalodata.com/api/pilot/skill/ext/v1/chat/async/result?task_id=<id>
Authorization: Bearer <token>

リクエストの送信

クエリの管理には scripts/pilot.sh を使用します。このスクリプトはトークンの読み込み、タスクの送信、ポーリングを処理するため、バックグラウンドプロセスや古いファイルは必要ありません。

複雑さ別の応答時間：

• 簡単なクエリ（単一の軸による検索。「米国の人気商品」など）：約 1 分
• 複雑なクエリ（複数の軸にまたがる検索、診断、比較）：2～3 分
• 非常に複雑なクエリ（レポートを伴う複数段階の分析）：数分（上限時間なし）

ステップ 1 — クエリを送信します：

bash <skill-path>/scripts/pilot.sh query "<user question>"

フォローアップの質問では task_id を使用します：

bash <skill-path>/scripts/pilot.sh query "<user question>" "<task_id>"

これにより、すぐに task_id が返されます（次のステップのために保存されます）。クレジットが不足している場合やトークンが無効な場合は、ここでただちにエラーが返されます。分析を実行中であることをユーザーに伝えてください。

ステップ 2 — 結果をポーリングします：

クエリの複雑さに応じてポーリングします。

• 簡単なクエリ → 45 秒後に最初のポーリング
• 複雑なクエリ → 90 秒後に最初のポーリング
• status が running の間は、状態が変わるまで 30 秒ごとに再度ポーリングします。

bash <skill-path>/scripts/pilot.sh result

呼び出すたびに、現在の状態が JSON で返されます。data.status を確認してください。

• running → 処理中です。待ってから再度ポーリングします。
• completed → 結果のフィールド（text、report、…）に値が設定されます。内容を表示します。
• error → data.error.message を表示します。
• cancelled → タスクはキャンセルされました。

result はステップ 1 と同じ task_id をポーリングします。特定のタスクをポーリングするには、引数として task_id を明示的に渡してください。

マルチターン会話

最初のリクエストでは、応答に task_id が含まれます。同じトピックについてフォローアップの質問をする場合は、必ず同じ task_id を再利用してください。これにより、KaloPilot に会話のコンテキストが引き継がれ、「最初のもの」や「昨日のものと比較して」といった参照を理解できるようになります。

会話の例：

1. 最初のメッセージ：{"query": "美国热门商品有哪些？"} → 応答に "task_id": "abc123" が含まれます
2. フォローアップ：{"query": "第一名的销售趋势怎么样？", "task_id": "abc123"}
3. さらにフォローアップ：{"query": "对比一下英国市场", "task_id": "abc123"}

ユーザーが明らかに異なるトピックに移った場合は、task_id を付けずに新しく開始してください。

レスポンス形式

すべての非同期レスポンスは { "success", "data", "message", "code" } でラップされています。 必要なフィールドは data の下にあります。

送信（query）：

{ "success": true, "data": { "task_id": "abc123", "status": "submitted" } }

実行中のポーリング（result）：

{ "success": true, "data": { "task_id": "abc123", "status": "running" } }

完了後のポーリング（result）：

{
  "success": true,
  "data": {
    "task_id": "abc123",
    "status": "completed",
    "message_id": "456",
    "text": "The main analysis text...",
    "report": "# Detailed Report\n\n...",
    "report_url": "https://www.kalodata.com/...",
    "token_usage": {...},
    "credits_consumed": 10
  }
}

レスポンスの表示方法

data.status が completed になった場合にのみ表示します。その後、data から次の内容を読み取ります。

1. text フィールドを表示します。これが主要な分析です。
2. report が null でない場合は、それも表示します（表や構造化データを含む Markdown レポートです）。
3. report_url が null でない場合は、ユーザーがブラウザーで開けるクリック可能なリンクとして表示します。例：「完全なレポートを表示：[リンク]」。重要：API レスポンスの report_url の値をそのままコピーしてください。この URL を構築、推測、捏造してはいけません。URL 内の task_id と tool_call_id パラメーターはサーバーが生成する一意の値であり、推測できません。レスポンスに report_url が存在しない、または null の場合は、リンクを表示しないでください。
4. 最後に消費クレジット数を記載します。例：「（10 クレジットを消費）」

エラーレスポンス

形式は 2 種類あります。

• リクエストの拒否（クレジット不足、無効なトークンなど。query で通知）：success が false で、トップレベルに message と code があります。
• タスクの失敗（result で通知）：data.status が error で、data.error.message にエラーが含まれます。

よくあるケース：

• クレジット不足：KaloData でクレジットをチャージする必要があることをユーザーに伝えてください。
• メンバーシップが必要：一部のデータには、より上位のプランが必要であることを伝えてください。
• その他のエラー：エラーメッセージをそのまま表示してください。

ユーザーが質問できる内容

KaloPilot は、TikTok Shop のすべての地域（US、UK、ID、MY、TH、VN、PH、SG、MX、DE、IT、FR、ES、BR、JP）で、次の項目を扱います。

• 商品：ランキング、売上トレンド、価格分析、急成長商品、セールスポイント分析、コメント／レビュー分析、画像検索（写真から類似商品を検索）
• ショップ：ストアランキング、売上高、商品構成、成長指標
• クリエイター／インフルエンサー：パフォーマンス、GMV、フォロワー分析、コラボレーションデータ、クリエイター検索
• 動画：話題の商品を紹介する動画、エンゲージメント指標、コンバージョン分析、動画スクリプトの抽出
• ライブ配信：ライブ販売データ、視聴者指標、配信中の商品パフォーマンス
• カテゴリ：市場規模、成長トレンド、競合状況、キーワードによるカテゴリ検索
• ユーザーのコレクション：保存／フォローした商品、ショップ、クリエイター、動画、動画スクリプトの表示
• URL 検索：TikTok、KaloData、Shopee、Lazada のリンクを貼り付けて、対象の詳細を取得
• KaloData FAQ：KaloData 自体の使い方に関する質問
• メンバーシップと料金：プランの詳細と料金情報
• 複数項目にまたがる分析：例：「米国のビューティーカテゴリで、最も売上に貢献しているクリエイターは誰ですか？」

各項目の詳細なツールパラメーター、フィルター、並べ替えオプションについては、該当するリファレンスファイルを参照してください。

項目	リファレンス
商品	references/products.md
ショップ	references/shops.md
クリエイター	references/creators.md
動画	references/videos.md
ライブ配信	references/livestreams.md
カテゴリ	references/categories.md
コレクション、URL 検索、FAQ、クレジット	references/utilities.md

ユーザーの質問に関連するリファレンスファイルだけを読んでください。すべてを読み込む必要はありません。

質問の例

ショップの診断 — KaloPilot は業界ベンチマークを自動で取得し、上位の競合と比較して診断レポートを出力します。

"帮我诊断一下这个店铺 https://kalodata.com/shop/xxx，分析它的优劣势"

価格帯別の商品選定 — 複数の価格帯を調べて比較します。

"美国 Beauty 类目 $20-50 和 $50-100 价格带分别有哪些爆款？对比一下各价格带的竞争格局"

動画スクリプトの分析 — 成果上位の動画からスクリプトを抽出し、タイムラインごとに分析します。

"帮我提取美国 Pet Supplies 类目近7天收入最高的5个视频脚本，总结爆款套路"

クリエイターの検索 — 特定の条件に合うクリエイターを見つけます。

"帮我找美国 Beauty 类目粉丝10万-50万、互动率高的达人，按带货收入排序"

複数ターンでの詳細分析：

User: "英国市场 Electronics 类目近30天表现怎么样？" User: "前三名的店铺分别是谁？详细对比一下" User: "第一名的店铺用了哪些达人？分析达人结构"

重要なルール

• ユーザーの質問はどの言語でも構いません。KaloPilot が多言語の質問を自動で処理します。
• 質問が曖昧な場合は、そのまま渡してください。KaloPilot が確認の質問をするか、妥当なデフォルト値を設定します。
• TikTok のデータに関する質問に、自分の知識で回答しないでください。必ず API にルーティングしてください。最新の市場データを持っているのは KaloPilot だけです。
• データを捏造しないでください。API 呼び出しに失敗した場合は、その旨を伝えてください。