Webデータ収集ツール Octoparse の日本チームで働いています。Octoparse の CLI（@octoparse-ai/octoparse-cli）を Windows の PowerShell から使い、Claude Code にも操作させてみたところ、ツールの不具合というより「PowerShell と組み合わせたときの癖」で何度も止まりました。同じところで止まる人のために、症状と対処をまとめます。
環境：Windows / PowerShell 5.1 / Node.js 20 / octoparse-cli 0.1.33
1. 日本語が文字化けし、JSON も壊れる
症状
octoparse capabilities --json などの出力で日本語が化け、出力を ConvertFrom-Json に渡すとパースエラーになる。
対処
最初にコンソールの出力エンコーディングを UTF-8 にします。
[Console]::OutputEncoding = [Text.Encoding]::UTF8
セッションごとに必要なので、毎回使うなら $PROFILE に書いておくと楽です。
2. JSON ファイルを渡すと読めない
症状
パラメータを JSON ファイルにして --params-file で渡すと、CLI 側で JSON として読めない。
原因
PowerShell 5.1 の Out-File -Encoding utf8 は BOM 付き UTF-8 で書き出します。先頭の BOM が JSON パーサーに嫌われます。
対処
BOM なしで書き出します。
$json = '{"aSIN":["B0XXXXXXX"],"review_Date_Time":"2025-1-1"}'
[IO.File]::WriteAllText("$PWD\params.json", $json)
[IO.File]::WriteAllText は既定で BOM なしの UTF-8 です。
3. ドキュメントのコマンドをそのまま貼るとエラー
症状
The '<' operator is reserved for future use.
原因
ドキュメントの octoparse cloud status <taskId> のような山括弧は「ここを置き換えて」という意味ですが、PowerShell では < がリダイレクト用の予約演算子です。
対処
実際の値に置き換えるか、変数に入れて渡します。
$tid = "a2d2dc6f-...."
octoparse cloud status $tid --json
4. API キーを渡すと「無効な制御文字」
症状
API キーをヘッダーに入れて Invoke-RestMethod を叩くと、「ヘッダーに無効な制御文字が含まれています」と言われる。直そうとして変数を作り直したら、今度は中身が空で 401。
原因
キーをコピーしたときに改行や見えない文字が混ざっていました。
対処
入力時に前後の空白と制御文字を落とします。画面にも履歴にも残らないよう Read-Host で受け取るのがおすすめです。
$key = (Read-Host "API key").Trim() -replace '[\x00-\x1F\x7F]', ''
$key.Length # 中身が入っているか長さだけ確認
キーをチャット（AI を含む）やログに貼らないようにしましょう。CLI は octoparse auth login で OAuth ログインもできます。
5. template view のパラメータが空
症状
octoparse template view <id> でテンプレートの詳細を見ても、parameters がどれも [] になる。パラメータなしでタスクを作ると、実行は成功するのに0件。
対処
v0.1.33 時点では、パラメータ定義は API か MCP から取ります。
$h = @{ "x-api-key" = $key }
Invoke-RestMethod "https://openapi.octoparse.com/api/agentTools/searchTemplates?id=1203" -Headers $h
返ってくる inputSchema に、受け付けるフィールド名（例：aSIN、review_Date_Time）が書いてあります。Claude などから MCP 経由で search_templates を呼んでも同じ情報が取れます。
パラメータ名は大文字小文字まで含めてテンプレートごとに違います。推測で渡すとエラーにならず0件で終わることがあるので、0件のときはまずここを疑います。
6. ユーザーブラウザモードの detect がタイムアウトする
症状
octoparse detect <URL> --browser user で自分の Chrome プロファイルを使おうとすると、拡張機能の応答待ち（45秒）で何度もタイムアウトする。
対処
--browser independent（独立ブラウザ）に切り替えると進みました。ただし独立ブラウザはログイン状態や地域設定を持たないので、サイトによっては表示が変わります（Amazon ではお届け先が海外になり、価格がドル表示になりました）。
ユーザーブラウザを使う場合は、スクレイピング専用の Chrome プロファイルを作り、普段使いのプロファイルや他人のプロファイルには触れない運用にしています。
7. ローカルでは取れるのに、クラウド実行で0件
症状
detect で作ったタスクが、ローカル実行（octoparse run）では取れるのに、クラウド実行では0件。
原因と対処
原因は2つありました。
- ループの XPath が絶対パスだった。ページ構造が少し違うだけで要素が見つからなくなります。検索結果の1件ずつを指す相対 XPath にします。
//div[@data-component-type='s-search-result']
- サイト側のボット対策。Amazon のように対策が強いサイトは、自作タスクだとクラウドで弾かれることがあります。この場合は公式テンプレートに切り替えるのが確実でした。テンプレートはブロック対策込みでクラウド実行されます。
まとめ
| 症状 | 対処 |
|---|---|
| 文字化け・JSON 破損 | [Console]::OutputEncoding = [Text.Encoding]::UTF8 |
| JSON ファイルが読めない |
[IO.File]::WriteAllText で BOM なし保存 |
< でエラー |
山括弧を実際の値か変数に置き換える |
| ヘッダーに制御文字 |
.Trim() と制御文字の除去 |
| パラメータが空・0件 | API / MCP の inputSchema でフィールド名を確認 |
| detect がタイムアウト |
--browser independent を試す |
| クラウドだけ0件 | 相対 XPath に直す。ダメなら公式テンプレート |
Claude Code に CLI を操作させる場合は、ここに書いた注意点をプロジェクトの CLAUDE.md に書いておくと、同じところで止まらなくなります。GitHub で公開しているプラグインのスキルにも同じ内容を入れています。