Skip to Content
ReferenceCLIコマンドlaunch

launch コマンド

launch コマンドは、kova init で発行した credential を環境変数として注入した状態で任意のエージェント CLI（claude / codex / openclaw / hermes 等）を起動するためのコマンドです。エージェントの環境変数を sanitize したうえで起動できます。

これは任意の高度用途コマンドです。 通常は claude を直接起動するだけで十分です。kova init で発行したエージェントキーは ~/.kova/config.json に保存されており、claude 等から呼ばれる新しい kova プロセスがそこから credential を直接読み取るため、launch ラッパは必須ではありません。launch は、子プロセスへ渡す環境変数を明示的に制御したい場合に使います。

旧 kova launch-agent は ADR-050 で削除されました。kova launch <agent> に読み替えてください（移行表）。

構文

kova launch <agent> [agent-options...]

<agent> 以降の引数はすべてエージェントプロセスへパススルーされます。-- デリミタは不要です。

引数

引数必須/任意説明
<agent>必須起動するエージェントコマンド名またはパス

組み込みエージェント: claude / codex / openclaw / hermes

上記以外の任意のパス・コマンド名も受け付けますが、KOVA_CREDENTIAL と KOVA_API_KEY_ID が $PATH 上で解決された任意のプロセスに注入される点に注意してください。

注入される環境変数

環境変数内容出典
KOVA_CREDENTIALアクティブプロファイルの API 鍵トークン~/.kova/config.json の profiles[<active>].credential
KOVA_API_KEY_IDAPI 鍵 ID（policy hash 検証用）~/.kova/config.json の profiles[<active>].apiKeyId

動作

  1. ~/.kova/config.json から activeProfile を読み込む
  2. アクティブプロファイルの credential と apiKeyId を取得
  3. 指定されたエージェントを stdio: 'inherit' で spawn し、KOVA_CREDENTIAL / KOVA_API_KEY_ID を注入
  4. エージェントプロセスの exit code をそのまま process.exit() で透過

使用例

Claude Code を起動

kova launch claude

Codex を起動

kova launch codex

エージェントオプションをパススルー

kova launch claude --model sonnet
kova launch claude --resume
kova launch codex --model o3

カスタムエージェントを起動

kova launch /usr/local/bin/my-agent

よくあるエラーと対処法

CREDENTIAL_REQUIRED

エラーメッセージ:

{
  "ok": false,
  "error": {
    "code": "CREDENTIAL_REQUIRED",
    "message": "No active profile or credential is missing. Run 'kova init' first."
  }
}

原因:

  • kova init のエージェントセットアップを完了していない
  • activeProfile が config に設定されていない
  • プロファイルの credential または apiKeyId が空

対処法:

# 状態確認
kova status
 
# 必要なら再セットアップ
kova init

UNKNOWN_ERROR（エージェントバイナリが見つからない）

エラーメッセージ:

{
  "ok": false,
  "error": {
    "code": "UNKNOWN_ERROR",
    "message": "Command not found: <agent>. Ensure it is installed and available on $PATH."
  }
}

対処法:

  • 指定したエージェント CLI がインストールされていることを確認する
  • which <agent> で PATH 上にあることを確認する

UNKNOWN_ERROR（spawn 失敗）

エラーメッセージ:

{
  "ok": false,
  "error": {
    "code": "UNKNOWN_ERROR",
    "message": "Failed to spawn agent: <reason>"
  }
}

対処法:

  • エージェントバイナリの実行権限を確認する
  • 環境変数（PATH など）が正しいシェルから引き継がれているか確認する

注意点

1. credential の漏洩防止

kova には credential を --api-key フラグや OWS_API_KEY 環境変数で渡す経路は 意図的に存在しません。漏洩リスク低減のため、credential は ~/.kova/config.json の保存と、launch が子プロセスへ注入する経路のみに限定されています。

2. エージェントの終了 = launch の終了

エージェントプロセスが exit すると launch も同じ exit code で終了します。エージェントが signal で停止した場合は Unix 規約に従い 128 + signum を返します。

3. アクティブプロファイルの確認

現在のアクティブプロファイルは kova status または kova config profile show で確認できます。プロファイルは kova init が自動生成・自動アクティブ化するため、CLI から切り替えるコマンドはありません。

# 現在のアクティブプロファイル確認
kova status
 
# 起動
kova launch claude

4. shell 評価の抑止

launch は shell: false で子プロセスを spawn するため、エージェント名にシェルメタ文字（;, &&, | 等）が含まれていても shell 評価されません。これはコマンドインジェクション対策です。

launch-agent からの移行

旧 kova launch-agent は ADR-050 で削除されました。次の表に従い読み替えてください。

旧コマンド新コマンド
kova launch-agentkova launch claude
kova launch-agent --agent codexkova launch codex
kova launch-agent --model Xkova launch claude --model X

関連コマンド

  • init — credential / プロファイルの発行（エージェントセットアップ）
  • config — config profile list / config profile show でプロファイル確認
  • status — 現在の activeProfile と authMethod を確認

関連項目

  • OperationKind 分類（agent モード = 非 TTY + credential、terminal モード = TTY + passphrase）
  • 用語集 — Kova の主要概念の定義
Last updated on
keystatus