DEV Community

Cover image for OpenClawでのApidog CLIの使い方
Akira
Akira

Posted on • Originally published at apidog.com

OpenClawでのApidog CLIの使い方

OpenClawは、ワークスペースを読み込み、execツールでシェルコマンドを実行し、その出力から次のアクションを決定するループ型のエージェントです。APIテストがGUI上で人のクリック待ちになっているなら、そのループには入っていません。apidog-cliを設定すれば、OpenClawはユニットテストと同じようにApidogのテストシナリオを実行し、終了コードを読み取り、失敗時は修正と再実行を行えます。

今すぐApidogを試す

このガイドでは、OpenClawでApidog CLIを継続的に使うための設定に絞って説明します。ポイントは、エージェントが守るルールをどこに置くか、exec経由でapidog runをどう実行するか、そして実行結果をどう判定するかです。

まず、Apidog CLIをインストールして認証を完了しておいてください。AIコーディングエージェントでApidog CLIをインストールする方法では、npmによるインストール、認証、初回実行を説明しています。この記事では、次のコマンドがバージョン番号を返し、すでにApidogアカウントへサインイン済みであることを前提にします。

apidog --version
Enter fullscreen mode Exit fullscreen mode

ここで対象とするOpenClaw

OpenClawは、ローカルマシン上で動作するオープンソースのローカルファーストAIエージェントです。ワークスペース、スキルセット、実際のシェルコマンドを実行するexecツールを持ちます。

コード補完プラグインやホスト型チャットボットではありません。ローカルでopenclawを実行し、ファイル編集やコマンド実行を確認したことがあれば、この手順を適用できます。

より広い設定については、以下も参照してください。

重要なのは、OpenClawがワークスペースファイルからプロジェクトルールを学ぶ点です。一度だけ「テストを実行して」と指示するのではなく、エージェント自身の標準動作にするにはAGENTS.mdを使います。

ステップ1: ApidogルールをAGENTS.mdに追加する

OpenClawはワークスペース内のファイルを常設の指示として読み込み、エージェントのコンテキストへ注入します。AGENTS.mdは、エージェントに何をどのように実行するかを伝える手続き的なルールブックです。Claude CodeのCLAUDE.mdに近い役割を持ちます。

OpenClawでは、デフォルトでワークスペースは~/.openclaw/workspaceです。agents.list[].workspaceを設定すれば、エージェントを任意のプロジェクトディレクトリへ向けられます。また、サブディレクトリごとのスコープ付きAGENTS.mdもサポートされています。詳細はOpenClawのAGENTS.mdリファレンスを確認してください。

対象ワークスペースのAGENTS.mdに、次のブロックを追加します。

## API testing with Apidog

- APIテストを実行するには、Apidog CLIを使用します: `apidog run -t <scenario_id> -e <env_id> -r cli`。
- 終了コード0はすべてのアサーションが成功したことを意味します。0以外は何かが失敗したことを意味します。これを合否のゲートとして扱ってください。
- マシンは`apidog login`で既に認証されています。`--access-token`フラグを追加したり、このファイルにトークンを置いたりしないでください。
- 見慣れないフラグがある場合は、推測する代わりに`apidog run --help`を実行してください。
Enter fullscreen mode Exit fullscreen mode

実運用では、後述するシナリオIDと環境IDを埋め込んでおくと、OpenClawが毎回同じ対象を実行できます。

チャットで一度だけコマンドやシナリオIDを伝えるのではなく、AGENTS.mdへ書くことが重要です。セッション内の指示は終了時に失われますが、ワークスペース内のルールは、以後のOpenClaw実行とチームメンバーの作業に残ります。

ステップ2: Apidogから実行コマンドを取得する

シナリオIDを手入力する必要はありません。Apidogでテストシナリオを開き、CI/CDタブから生成されたコマンドをコピーします。

apidog run -t 1234567 -e 890123 -r cli
Enter fullscreen mode Exit fullscreen mode

各フラグの意味は次のとおりです。

フラグ 内容
-t テストシナリオID
-e 実行環境ID
-r cli ターミナル出力用レポーター

コピーした実際のIDをAGENTS.mdへ反映してください。

- チェックアウトAPIのテストは、常に次のコマンドで実行してください:
  `apidog run -t 1234567 -e 890123 -r cli`
Enter fullscreen mode Exit fullscreen mode

これにより、OpenClawが正しいシナリオを正しい環境へ実行できます。フラグを調整する場合は、Apidog CLI完全ガイドとapidog runコマンドリファレンスを参照してください。

ステップ3: エージェントにテストを実行させる

AGENTS.mdを配置したら、対象プロジェクトでOpenClawを起動します。APIに影響する変更を加えた後、または単にチェックの実行を依頼すると、OpenClawはexecツール経由でapidog runを実行します。

例えば、次のように依頼できます。

チェックアウトAPIの変更を確認し、Apidogのシナリオを実行してください。
失敗した場合は、出力を確認して修正を試みてください。
Enter fullscreen mode Exit fullscreen mode

OpenClawのexecはパーミッションモードで制御されます。利用可能なモードは以下です。

  • deny
  • allowlist
  • ask
  • auto
  • full

詳細はOpenClawのパーミッションモードを参照してください。

コーディングエージェントでは、通常autoが実用的です。許可リストにあるコマンドは確認なしで実行され、それ以外は実行前にレビューされます。

askを使用している場合、OpenClawはapidog runの前に承認を求めます。ステージング環境に対する読み取り専用テストを自動化したい場合は、一度承認するか、apidogコマンドを許可リストへ追加してください。

設定はopenclaw.jsonのtools.exec配下で行います。

ステップ4: OpenClaw内でレポートを読み取る

-r cliレポーターは、リクエスト、アサーション、失敗内容、期待値と実際値の差分をターミナルへ出力します。

OpenClawが次のアクションを判断するには、このインライン出力が必要です。そのため、レポーターにはcliを残してください。

ブラウザで確認したり、チームへ共有したりするHTMLレポートも必要なら、htmlを追加します。

apidog run -t 1234567 -e 890123 -r cli,html
Enter fullscreen mode Exit fullscreen mode

htmlレポーターは自己完結型のレポートを./apidog-reportsへ出力します。OpenClawがターミナル出力を読めるように、htmlのみではなくcli,htmlを使います。

JUnit形式など、CIダッシュボード向けのレポーターについては、Apidog CLIテストレポートガイドを参照してください。

OpenClaw自身のループ内でテストする

設定後の目標は、あなたが毎回テスト実行を指示しなくても、OpenClawがAGENTS.mdのルールに従って実行することです。

例えば、OpenClawがチェックアウトレスポンスを構築するハンドラーを編集しているとします。編集後のループは次のようになります。

  1. コードを編集する
  2. apidog runでステージング環境のシナリオを実行する
  3. 終了コードとCLI出力を確認する
  4. 成功なら次の作業へ進む
  5. 失敗なら、失敗したアサーションを確認する
  6. 修正して再実行する

失敗時には、ステータスコード、欠落フィールド、値の不一致などをCLI出力から確認できます。APIテストは、ユニットテストと同じ「編集 → テスト → 修正」ループの一部になります。

これはエージェント運用における「委任して検証する」モデルです。シナリオはApidog上で視覚的に管理し、OpenClawにはCLIで実行させます。定期的に実行ログと終了コードを確認し、エージェントが結果を正しく解釈しているかを検証してください。

関連する運用パターンは、以下でも確認できます。

OpenClawが実際にCLIを実行したか確認する

エージェントが実際には達成していない成功を報告することがあります。テスト実行を検証する際は、次の3点を確認してください。

1. 実行コマンドを確認する

OpenClawのトランスクリプトには、execで実行したコマンドとその出力が表示されます。

次のような実行行と、その直後の出力を探してください。

apidog run -t 1234567 -e 890123 -r cli
Enter fullscreen mode Exit fullscreen mode

OpenClawが「テストに合格した」と報告していても、このコマンドや出力が存在しなければ、実行結果ではなく要約を返しただけの可能性があります。その場合は、再実行し、生の出力を表示するように依頼してください。

2. 終了コードを確認する

OpenClawには直接、次のように確認できます。

そのapidog runコマンドの終了コードは何でしたか？
Enter fullscreen mode Exit fullscreen mode

apidog runは、すべてのアサーションが成功した場合に終了コード0を返します。いずれかが失敗した場合は、0以外です。

つまり、判定は次のように行えます。

終了コード 0      : 合格
終了コードが0以外 : 不合格
Enter fullscreen mode Exit fullscreen mode

OpenClawの要約が「合格」でも、終了コードが0以外なら不合格として扱ってください。

3. シナリオIDと環境IDを確認する

実行結果にscenario not foundが含まれる場合、OpenClawがIDを誤って記憶した、または推測した可能性があります。

以下を再確認してください。

  1. AGENTS.md内の-t値
  2. AGENTS.md内の-e値
  3. ApidogのCI/CDタブで生成されたコマンド

IDの正しい情報源は、ApidogのCI/CDタブで生成されたコマンドです。確認済みの値をAGENTS.mdに保存してください。

オプション: Apidog MCPサーバーを接続する

多くのケースでは、exec経由のapidog runで十分です。さらに、モデルコンテキストプロトコル（MCP）を使う方法もあります。

OpenClawはMCPサーバーをサポートしており、次のように追加できます。

openclaw mcp add <name>
Enter fullscreen mode Exit fullscreen mode

この操作により、~/.openclaw/openclaw.jsonのmcp.servers配下にサーバー定義が書き込まれます。--commandや--argなどのstdioフラグも利用できます。詳細はOpenClawのMCPドキュメントを参照してください。

Apidog MCPサーバーを使うと、OpenClawはMCP経由でAPI仕様を参照できます。

役割を分けると分かりやすくなります。

  • Apidog CLI: テストを実行する
  • Apidog MCPサーバー: エージェントにAPI仕様を提供する

つまり、CLIはコード変更後の検証、MCPはコード作成中のスキーマ参照に使います。

OpenClawが間違った場合の対処

セットアップ時に起こりやすい問題と対応を整理します。

AGENTS.mdのルールが無視される

OpenClawが一般的なコマンドを実行したり、何も実行しなかったりする場合、対象のAGENTS.mdがコンテキストに読み込まれていない可能性があります。

確認項目は次のとおりです。

  • AGENTS.mdがエージェントのアクティブなワークスペース内にあるか
  • ルールが誤ったサブディレクトリに置かれていないか
  • OpenClawが対象ディレクトリのスコープ付きAGENTS.mdを読める構成か
  • セッションを再起動して設定を再読み込みしたか

execがブロックされている

apidog runが実行されない場合、tools.execのパーミッションモードを確認してください。

対応は次のいずれかです。

  • モードをautoへ変更する
  • apidogを許可リストへ追加する
  • askモードで実行を承認する

すべてのコマンドを無制限に許可する必要はありません。安全なOpenClawインストールガイドを参照し、必要なコマンドだけを許可してください。

--access-tokenを追加しようとする

OpenClawが--access-tokenを付与しようとする場合、公開例から推測している可能性があります。

すでにapidog loginで認証済みなら、トークンをコマンドへ渡す必要はありません。AGENTS.mdには実際のトークンを絶対に書き込まないでください。

認証方法の詳細は、Apidog CLI認証を参照してください。

存在しないフラグを使う

「不明なオプション」エラーは、インストール済みのCLIバージョンに存在しないフラグをOpenClawが推測したことを示します。

推測ではなく、必ず次のコマンドで確認させてください。

apidog run --help
Enter fullscreen mode Exit fullscreen mode

表示されたヘルプにあるフラグだけを使用します。

失敗した実行を合格と報告する

最もコストが高い問題です。要約より終了コードを優先してください。

終了コード 0      : 合格
終了コードが0以外 : 不合格
Enter fullscreen mode Exit fullscreen mode

AGENTS.mdに終了コードのルールを明記し、OpenClawの報告と実行ログが一致することを確認します。この考え方は、CodexにおけるApidog CLIやClaude CodeとOpenClawの違いでも応用できます。

日常的なエージェントをテスト済みループへ変える

設定はシンプルです。

  1. インストールガイドに従ってapidog-cliをインストールする
  2. apidog loginで認証する
  3. ワークスペースのAGENTS.mdにApidog実行ルールを追加する
  4. ApidogのCI/CDタブからコピーしたシナリオIDと環境IDを設定する
  5. tools.execでapidog runを実行可能にする
  6. OpenClawのトランスクリプトと終了コードで実行結果を確認する

これでOpenClawは、コード編集と同じループの中でAPIテストを実行し、結果を読めるようになります。壊れたエンドポイントをデプロイ後に発見するのではなく、変更作業中に検出できます。

テストシナリオは引き続きApidog上で視覚的に構築し、OpenClawには一行のCLIコマンドで実行させます。Apidogをダウンロードして1つのシナリオを作成し、そのapidog runコマンドをAGENTS.mdへ追加してみてください。

エージェントが存在しないCIパイプラインでも同じゲートを使いたい場合は、GitHub ActionsにおけるApidog CLIで、シークレット、レポーター、終了コードによるゲート設定を確認できます。

Top comments (0)