GuidesOneMux

本番環境でのCline:セッション設定と安全な復旧

ClineCoreのセッション設定、ランタイム設定とプロバイダー設定の分離、安全なリトライと復旧ルールの設計を実践的に解説します。

AI

要約 · TL;DR

ClineCoreでは、バックエンドモード、機能、ツールポリシー、自動化などのランタイム設定と、各セッションで設定するプロバイダーやモデルを分けて管理できます。このガイドでは、その分離を明確にし、作業をむやみに繰り返すのではなく、セッションIDと永続化された状態に基づいて復旧処理を設計する方法を説明します。

要点

  • ランタイム、ツール権限、プロバイダー/モデルの設定は、それぞれ分けて判断しましょう。
  • リトライする前に、セッションIDと永続化されたメッセージを使って障害の状況を調べましょう。
  • リトライによって副作用が重複する可能性を考慮し、ワークフローに応じたチェックポイントと復旧ルールを定義しましょう。
  • APIリファレンスにはセッション操作が記載されていますが、リトライの意味論、チェックポイント形式、プロバイダー互換性の保証は示されていません。
目次 (9)

ClineCoreを使うと、アプリケーションからセッションの作成、ランタイムの選択、ツール権限、セッション履歴を制御できます。本番ワークフローを運用するうえで重要なのは、単に失敗した呼び出しをリトライするかどうかではありません。作業を再実行する前に、すでに何が行われたかをどう判断するかです。

以下の設定例は説明用であり、テスト済みのデプロイ手順ではありません。ClineCore APIリファレンスには、ここで取り上げるオプションとメソッドが記載されています。正確な型と動作については、インストールするSDKのバージョンを確認してください。

ランタイム設定とモデル設定を分ける

設定を分ける際は、次の3つに整理すると便利です。

  • ランタイム: バックエンドの選択、クライアントの識別情報、必要に応じたリモート接続やハブ接続の設定。
  • 実行ポリシー: ツールポリシー、機能、自動化APIを有効にするかどうか。
  • セッションのモデル設定: 特定のセッションに対するプロバイダーID、モデルID、認証情報、ワークスペースのパス、利用可能なツール。

こうしておくと、モデルを変更するときもランタイムポリシーを独立して管理しやすくなります。ただし、プロバイダー固有のフィールドを相互に置き換えられるわけではありません。選択したプロバイダーに対して、providerId、modelId、apiKeyが引き続き有効である必要があります。APIリファレンスは、あらゆるプロバイダーやエンドポイントとの互換性を保証していません。

ランタイムを作成してセッションを開始する

前提条件:デプロイするCline SDKのバージョンをインストールし、アプリケーションのシークレット管理方法に従って認証情報を用意し、エージェントが使用できるツールを決めます。認証情報をログやセッションメタデータに含めないでください。

import { ClineCore } from "@cline/sdk"

const cline = await ClineCore.create({
  clientName: "repo-maintenance-worker",
  backendMode: "auto",
  toolPolicies: {},
  automation: false,
})

const session = await cline.start({
  prompt: "Inspect the repository and report failing tests. Do not modify files.",
  source: "scheduled-check",
  interactive: false,
  sessionMetadata: { jobId: "job-123" },
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
    systemPrompt: "Follow the task scope and report actions taken.",
    cwd: process.cwd(),
    workspaceRoot: process.cwd(),
    enableTools: true,
    enableSpawnAgent: false,
    enableAgentTeams: false,
  },
})

console.log(session.sessionId)

上記のプロバイダーとモデルの値は、APIリファレンスの例に合わせたものです。推奨設定を示すものでも、その例を超えてプロバイダーとの互換性を主張するものでもありません。リファレンスには、backendModeの値としてauto、local、hub、remoteと、任意のhubおよびremote設定が記載されています。特定のデプロイに最適なモードは定義されていません。モードは慎重に選び、実際の環境で接続性と権限を検証してください。

空のtoolPoliciesオブジェクトはセキュリティポリシーではありません。インストールしたSDKがサポートするポリシー型に従い、デフォルトとセッションごとのポリシーを明示的に設定してください。クライアントがツール実行機能や承認コールバックを提供する場合はcapabilitiesを使い、制限対象の操作が実際に拒否されることをテストしてください。

セッション状態を基準にリトライルールを設計する

ネットワークエラーやワーカーのタイムアウトが起きても、エージェントが作業を完了する前に停止したとは限りません。最初のプロンプトを再実行すると、編集、外部呼び出し、その他の副作用が重複するおそれがあります。APIリファレンスにはget、readMessages、getAccumulatedUsage、abort、stop、restoreが記載されていますが、自動リトライ、厳密に1回だけの実行、チェックポイントの内容については定義されていません。

より安全な運用手順は次のとおりです。

  1. セッションIDをすぐに記録する。 再起動したワーカーが同じセッションを特定できるよう、ジョブIDとともに永続化します。
  2. 障害を分類する。 終了が確認できた失敗と、完了したかどうかが不明なタイムアウトや接続断を区別します。
  3. 再送信する前に確認する。 getとreadMessagesを使い、セッションのメタデータと永続化されたメッセージを確認します。必要に応じて累積使用量も運用上の手掛かりとして確認できますが、特定の操作が完了した証拠にはなりません。
  4. 復旧方法を慎重に選ぶ。 セッションがまだアクティブなら、待機するか、abortするか、stopするかを判断します。作業を続ける場合、sendにはセッションIDと後続プロンプトを指定できます。チェックポイントが利用可能で適切な場合、APIにはrestoreが用意されています。必要な入力と意味についてはSDKのドキュメントを確認してください。
  5. 副作用を安全に再実行できるようにする。 エージェント自身のセッション状態の外部で行う操作には、必要に応じてアプリケーションレベルの冪等性キー、重複排除、または人による承認手順を使います。

startを無条件のリトライループで囲むのは避けてください。呼び出し側が応答を受け取れなかっただけで、最初のリクエストによってセッションが作成されている可能性があります。その状態で別のstartを実行すると、別個の作業が作成されることがあります。APIリファレンスにはstartの冪等性キーが記載されていないため、存在するものと考えないでください。

本番環境でよくある障害のトラブルシューティング

セッションが意図しないランタイムで開始される

選択されたバックエンドモードと、秘密情報を含まないセッション識別子をログに記録します。ワーカーが実行される環境に照らして、backendMode、hub、remoteの各オプションを確認してください。リファレンスではこれらをランタイム選択オプションとして説明していますが、自動フェイルオーバーの動作は記載されていません。想定したフォールバックに依存せず、使用するSDKバージョンでautoがどのように動作するか検証してください。

ツールが使えない、または想定外に許可される

セッションのconfigと、適用されるデフォルトおよびセッションごとのtoolPoliciesまたはcapabilitiesの両方を確認してください。リファレンスでは、これらをツールポリシー、およびクライアント側で管理する実行機能/承認制御として説明しています。提示されたAPI概要にはポリシーの優先順位が記載されていないため、インストールしたSDKのドキュメントで確認し、許可されるケースと拒否されるケースの両方をテストしてください。

実行中にワーカーの接続が切れる

セッションIDとジョブIDを、耐久性のあるアプリケーション状態に保存してください。再起動後は既存のセッションを確認してから、sendで続行するか、停止するか、チェックポイントから復元するかを判断します。応答がないことだけを根拠に、完了したと推測しないでください。

プロバイダーまたはモデルの設定に失敗する

選択した構成について、プロバイダーとClineのドキュメントを参照し、プロバイダーID、モデルID、認証情報、エンドポイントの要件を確認してください。ClineCoreのリファレンスにはプロバイダー/モデル設定の形式が示されていますが、任意のOpenAI互換エンドポイントやプロバイダー固有のパラメーターがそのまま動作するとは保証されていません。

本番環境向けチェックリスト

  • セッションIDを永続的に保存し、ログやメタデータにシークレットを含めない。
  • ツール権限を明示的に設定し、承認と拒否の経路をテストする。
  • 失敗が確定した操作と、結果が不明な操作を区別する。
  • 作業を再送信する前にセッション履歴を確認する。
  • 外部への副作用は冪等にするか、再実行前に承認を必須にする。
  • 実際のデプロイ環境でバックエンドとプロバイダーの動作を検証する。
  • SDKで定められたライフサイクルに従い、正常なシャットダウン時にランタイムリソースを破棄する。

実務上のルールはシンプルです。何をリトライするのか把握してからリトライしてください。ClineCoreにはセッションや復旧に関係するAPIがありますが、本番環境で安全に運用できるかどうかは、アプリケーション側でのジョブ状態の永続管理、権限設計、副作用の重複への対処にも左右されます。

よくある質問

モデルプロバイダーから独立しているClineCoreの設定はどれですか?

`clientName`、`backendMode`、任意のハブまたはリモート設定、capabilities、ツールポリシー、自動化などのランタイムオプションは、セッションのプロバイダーやモデルのフィールドとは別に設定できます。各オプションの正確な動作は、使用中のSDKバージョンで確認してください。

タイムアウト後にClineCore.startをリトライすべきですか?

むやみにリトライしないでください。タイムアウトだけでは、セッションが作成されたかどうかはわかりません。セッションIDを取得できた場合は永続化し、新しい作業を開始する前に既存のセッションを確認してください。提示されたAPIリファレンスには、`start`の冪等性キーは記載されていません。

ClineCoreでは失敗したセッションを復元できますか?

APIリファレンスには`restore`メソッドが記載されていますが、提示された概要では必要な入力やチェックポイントの意味は説明されていません。復旧設計に組み込む前に、インストールしたSDKのドキュメントを確認してください。

この設定は、どのOpenAI互換プロバイダーでも動作しますか?

参照されているClineCoreのドキュメントでは、その点は保証されていません。プロバイダーの互換性と利用可能なパラメーターは、エンドポイントに対するサポート内容と選択したプロバイダー設定によって異なります。相互に置き換えられると想定せず、確認してください。

関連記事