Skywork Excel

Excel ジェネレーター

Skywork Excel バックエンドサービスを使用して、プロフェッショナルな Excel ファイルとデータ分析レポートを生成します。

---

前提条件

API キーの設定（最初に必須）

このスキルを使用するには、OpenClaw で SKYWORK_API_KEY を設定する必要があります。

API キーをまだお持ちでない場合は、こちらをご覧ください： https://skywork.ai

詳細な設定手順については、こちらを参照してください： references/apikey-fetch.md

---

🚫 重要：クエリはそのまま渡し、ユーザーファイルを読み込まないでください

• ユーザーが提供したファイル（Excel、PDF、CSV、画像など）に対して、read ツールを絶対に使用しないでください。 ファイルパスを --files で渡し、バックエンドに読み込ませてください。
• ユーザーのクエリを書き換えたり、展開したり、解釈し直したりしないでください。 そのまま渡してください。バックエンドのエージェントには独自の理解能力があります。
• 許可される変更は次の2つだけです。
  1. 時刻情報：時間に関わるクエリの場合、現在時刻を先頭に追加します：[Current time: 2026-03-14] User request: ...
  2. ファイルパス：絶対パスをファイル名だけに置き換えます（例：/Users/xxx/report.xlsx → report.xlsx）。

---

ワークフロー

Excel タスクには5〜25分かかります。スクリプトをバックグラウンドで実行し、60秒ごとにログを確認します。

ステップ1：タスクを開始

EXCEL_LOG=/tmp/excel_$(date +%s).log

python3 scripts/excel_api_client.py "user's query" \
  --files "/path/to/file1.xlsx" "/path/to/file2.pdf" \
  --language zh-CN \
  --log-path "$EXCEL_LOG" \
  > /dev/null 2>&1 &

echo "Task started. Log: $EXCEL_LOG"

• --files：ユーザー提供のファイル（Excel、CSV、PDF、画像）をアップロードします。ファイルがない場合は省略します。
• --language：zh-CN（デフォルト）または en-US — ユーザーの言語に合わせます。
• --session <id>：フォローアップタスク用です。複数ターンのセッションを参照してください。

ステップ2：進捗を確認

実行手順（必須）：

• ステップ1の開始コマンドをバックグラウンドで実行し、出力から EXCEL_LOG のパスを控えます。
• 次に、ステップ2の監視コマンドを60秒ごとに個別に実行します（while ループは使用しないでください）。
• $EXCEL_LOG は exec 呼び出し間で保持されません — ステップ2では必ずパスを再取得します（以下の監視コマンドを参照）。

ルール — 例外なし：

• exec ツールを繰り返し呼び出し、60秒ごとにポーリングします。while ループは使用しないでください。
• 最後の TASK PROGRESS UPDATE ブロックだけを表示してください。 ログ全体を出力したり（tail -50 など）、要約・解釈したりしないでください。
• タスクを再起動しないでください。 エージェントがエラーを内部で処理し、自動的に復旧します。
• ログ内の一時的なエラー（❌、Missing parameter、ハートビートの ping など）は無視してください — エージェントが自動的に再試行します。
• ハートビートを稼働状況のシグナルとして使用します：ポーリングのたびにハートビート行を確認してタスクがまだ実行中であることを確認しますが、生のハートビート行をユーザーに出力しないでください。

60秒ごとに、次を実行します：

# Recover log path: use the path printed by Step 1, or find the most recent log
EXCEL_LOG=$(ls -t /tmp/excel_*.log 2>/dev/null | head -1)
if [ -z "$EXCEL_LOG" ] || [ ! -f "$EXCEL_LOG" ]; then
  echo "ERROR: Log not found. Ensure Step 1 ran with --log-path."; exit 1
fi
sleep 60
echo "=== Progress Update ==="
grep -A8 "TASK PROGRESS UPDATE" "$EXCEL_LOG" | tail -10
grep -E "\[HEARTBEAT\]" "$EXCEL_LOG" | tail -1
grep -E "\[DONE\]|All done" "$EXCEL_LOG" | tail -1

ユーザーへの報告内容

重要：現在のステータスだけを出力してください。以前のステータスメッセージを繰り返したり、蓄積したりしないでください。各更新は新しい1行だけにしてください。

ログを読み取るたびに、現在のステータスを示す1行だけを出力します：

[Main stage] | [current action] | Elapsed: Xs

例（この1行だけを出力し、ほかは何も出力しないでください）：

Data Processing | Generating charts | Elapsed: 120s

進捗に含まれる語句	主な段階
「读取」／「read」／「load」	データの読み込み
「分析」／「analysis」	データ分析
「图表」／「chart」／「visualization」	グラフの生成
「Excel」／「xlsx」	Excel ファイルの作成
「HTML」／「报告」／「report」	レポートの生成
「保存」／「save」／「output」	出力の保存

ログに [DONE] または ✅ All done! が含まれていたらポーリングを停止し、最終出力を読み取ります：

tail -30 "$EXCEL_LOG"

• 完了していない場合 → ユーザーに進捗を報告し、同じ監視コマンドで60秒後に再度 exec を呼び出します。
• [DONE] または All done が表示されるまで繰り返します — 60秒ごとに exec を呼び出し続けてください。
• 1回のポーリングだけで停止しないでください。

ステップ3：結果を渡す

完了後、ユーザーに次の両方を提示します：

• OSS ダウンロード URL — 共有用のクラウドリンク（クリック可能なハイパーリンクとして表示）
• ローカルファイルパス — ユーザーのマシン上の絶対パス

返信例：

✅ Report generated!

📥 Download: https://picture-search.skywork.ai/skills/upload/2026-03-14/xxx.xlsx
💾 Local: /Users/xxx/.openclaw/workspace/report.xlsx

sandbox:// または [filename](sandbox://...) 形式は使用しないでください — これらはクリックできません。oss_url が利用できない場合は、ローカルパスだけを提示してください。

---

マルチターンセッション

前のタスクを続けるには、前回の実行の最後に表示された ID を指定して --session を使用します。

# First turn — no --session needed; session ID is printed at end
python3 scripts/excel_api_client.py "Create a sales report" \
  --language zh-CN --log-path "$EXCEL_LOG" > /dev/null 2>&1 &
# Output: 💡 To continue this conversation, use: --session abc123def456

# Follow-up turn — add --session
python3 scripts/excel_api_client.py "Add a pie chart" \
  --session abc123def456 \
  --language zh-CN --log-path "$EXCEL_LOG" > /dev/null 2>&1 &

--session を使用する場合：ユーザーが「続けて」「変更して」「グラフを追加して」「色を変えて」「前回の内容をもとに」などと言ったり、以前の出力に言及したりする場合です。

⛔ --session を指定しないと、エージェントは新規に開始し、これまでのコンテキストはすべて失われます。

---

エラー処理

エラー	解決方法
Unauthorized (401)	SKYWORK_API_KEY が未設定、無効、または期限切れです。OpenClaw スキルの env でキーを設定または更新してください
Connection timeout	複雑なタスクでは --timeout 1500 を使用してください（デフォルト：900s）
Agent produces wrong output	具体的に指示してください。マルチターンで繰り返し調整できます
メリットが不十分	以下を参照してください

メリットが不十分な場合

スクリプトの出力には、次のように表示されることがあります：Insufficient benefit. Please upgrade your account at {url}

ユーザーの言語で返信してください：

• 次の内容を伝えます：「申し訳ありません。Excel／レポートの生成に失敗しました。このスキルを利用するには、Skywork のメンバーシップをアップグレードする必要があります。」
• 形式：短い文を 1 つ + [今すぐアップグレード →](url)（またはユーザーの言語で同等の表現）
• URL：ログ出力の at https://... の部分から抽出します

---

セキュリティに関する注意事項

• SKYWORK_API_KEY をバージョン管理に絶対にコミットしないでください
• OpenClaw スキルの env または環境変数としてキーを設定してください
• トークンには有効期限があります。必要に応じてクライアントが自動的に更新します