【ITニュース解説】OpenCode and Kilo Code With Any OpenAI-Compatible Provider: Config Files That Work, and the Context Limit Trap

OpenCodeとKilo Codeは、システムエンジニアを目指す初心者がAIモデルを活用した開発を行う際に利用できる強力なツールだ。これらのツールは、OpenAIが提供する公式のAIサービスだけでなく、OpenAIと互換性のある様々なAIプロバイダを開発環境に統合することを可能にする。これにより、開発者は特定のAIサービスに縛られず、多様なモデルを試したり、自身のプロジェクトに最適なAIソリューションを選択したりできるようになる。しかし、これらのツールで外部のAIプロバイダを適切に設定し、予期せぬ問題を避けるためには、いくつかの重要な設定ポイントを理解する必要がある。

まず、OpenAI互換のAIプロバイダを利用する上で共通して必要となる基本的な情報がある。一つは「ベースURL」で、これはAIプロバイダのAPIエンドポイントのアドレスを示す。このURLは /v1 で終わる形式であるべきであり、例えば https://api.example.com/v1 のようになる。ここで注意すべきは、/chat/completions のような具体的なパスを追加してはならない点だ。クライアントツールが自動的に必要なパスを追加するため、余計なパスを含めるとエラーの原因となる。次に「APIキー」は、AIプロバイダが提供するサービスを利用するための認証情報であり、これは機密性が非常に高い。セキュリティのため、APIキーは設定ファイルに直接記述せず、システムに「環境変数」として設定し、設定ファイルからは {env:YOUR_API_KEY_NAME} のように参照するのが安全な方法だ。これにより、誤ってAPIキーを公開してしまうリスクを低減できる。さらに、「モデルID」はプロバイダが提供する個々のAIモデルを特定するための正確な識別子だ。プロバイダが公開しているモデルリストから正確なIDを確認することが不可欠で、短いエイリアスや表示名では「モデルが見つかりません」というエラーが出ることが多いため注意が必要だ。そして、各モデルが処理できる入力情報の量を示す「コンテキストウィンドウ」と、一度に生成できる応答の最大長を示す「最大出力トークン」の数値も必要になる。これらの数値は、後述する「コンテキストリミットの落とし穴」を回避するために非常に重要だ。

OpenCodeで外部プロバイダを設定する場合、通常はユーザーのホームディレクトリにある ~/.config/opencode/opencode.json ファイル、またはプロジェクトのルートディレクトリにある opencode.json ファイルを使用する。この設定ファイル内で、provider ブロックを使って新しいAIプロバイダを定義する。例えば、apiclaw というプロバイダIDを自分で設定し、その中に利用するnpmパッケージ名（例：@ai-sdk/openai-compatible）、プロバイダの表示名、そして options として baseURL と apiKey を記述する。apiKey には、先ほど説明した環境変数からの参照 {env:APICLAW_API_KEY} を使うのが良い。さらに、models ブロックでは、そのプロバイダが提供する各モデルの詳細を設定する。ここで特に重要なのが、モデルの limit ブロック内で context（コンテキストウィンドウ）と output（最大出力トークン）の値をプロバイダの仕様に合わせて正確に設定することだ。設定ファイルのトップレベルにある model キーでは、providerid/modelkey の形式で、デフォルトで使用するモデルを指定する。設定が完了したら、OpenCode内で /models コマンドを実行して、設定したモデルが正しくリストされているかを確認し、簡単なプロンプトを送信してプロバイダのログでリクエストが正しく処理されているかを検証することが推奨される。

Kilo Codeでも同様に、外部プロバイダを設定する方法がいくつかある。一つは、Kilo CodeのVS Code拡張機能のインターフェースを利用する方法だ。VS Codeの設定画面にある「Providers」タブから「Custom provider」を選択し、必要な情報を入力していくことで設定できる。もう一つは、Kilo CLIを使う場合で、この場合はグローバル設定ファイルである ~/.config/kilo/kilo.jsonc に設定を記述する。Kilo CodeのCLIにおいて、環境変数を参照する {env:...} 形式の設定は、このグローバル設定ファイルに記述された内容からのみ正しく解決されることが多い。プロジェクトレベルのファイルに記述しても環境変数が解決されず、認証に失敗することがあるため注意が必要だ。Kilo Codeでも provider ブロックを設定し、options で baseURL と apiKey、そして models ブロックで各モデルの詳細を設定する。ここでも limit ブロックで context と output を正確に設定することが極めて重要となる。さらに、モデルがツール呼び出し（AIが特定の機能や外部サービスを利用する能力）をサポートしている場合は、tool_call: true と設定する必要がある。設定後には kilo models コマンドで、設定したモデルがKilo Codeに正しく認識されているかを確認できる。

AIプロバイダを利用する上で最も陥りやすい問題の一つに「コンテキストリミットの罠」がある。OpenCodeやKilo Codeは、ツールに組み込まれている既知のAIモデルについては、そのコンテキストウィンドウのサイズを自動的に把握している。しかし、カスタムで追加した外部プロバイダのモデルについては、そのコンテキストサイズに関する情報をツールは自動では知らない。そのため、設定ファイル内で limit ブロックを使って context と output の値を明示的に設定してあげる必要がある。もしこの limit 設定を怠ると、クライアントツールはモデルが処理できる会話の長さを知らないまま、ユーザーとの会話を続けてしまう。Kilo Codeの場合、limit 設定がないカスタムモデルのコンテキストサイズはゼロとして扱われるため、この問題はより顕著になる。その結果、会話が長くなると、AIエージェントが古い会話を要約して新しい会話のためのスペースを作る「コンパクション」という重要な処理が全く行われない。会話の履歴が際限なく蓄積され、最終的にはAIプロバイダが「リクエストが長すぎる」という理由で処理を拒否する。この現象は、あたかもAIプロバイダが突然不安定になったかのように見えるが、実際には設定不足が原因で起こる。このようなエラーはセッション開始から長時間経過してから発生することが多いため、原因の特定が難しい。この問題を避けるためには、プロバイダが公開しているモデルの実際のコンテキストウィンドウと最大出力トークンを正確に limit 設定に反映させる必要がある。実際の数値よりも少し低い値を設定することは問題ないが、実際の数値よりも高い値を設定すると、結局同じエラーが発生する可能性があるため注意が必要だ。

これらの設定プロセス中に遭遇する可能性のあるいくつかのエラーとその解決策も理解しておくべきだ。「Invalid API key」や「401エラー」は、APIキーが間違っているか、キーに余分なスペースが含まれている場合、またはKilo Codeにおいて環境変数がグローバル設定ファイルから正しく解決されていない場合に発生する。「Model not found」や「404エラー」は、指定したモデルIDがプロバイダが提供する正確なIDと一致しない場合、あるいはベースURLの形式が間違っている（/v1 が不足している、または /chat/completions のような余計なパスが含まれている）場合に発生しやすい。また、モデルがリストに表示されるにもかかわらずツール呼び出し（ファンクションコール）が無視される場合は、そのモデル自体がツール呼び出しを十分にサポートしていないか、Kilo Codeで tool_call: true の設定が漏れている可能性がある。このような場合は、ツール利用の実績があるモデルで試してみるのが良いだろう。セッションが長くなると「コンテキスト長エラー」で停止する場合は、先述したように limit 設定が不足しているか、設定値が不適切であることが原因である。そして、OpenCodeでResponses APIを使用する必要がある場合は、@ai-sdk/openai-compatible ではなく @ai-sdk/openai パッケージを使用する必要があるが、これは利用するプロバイダが /v1/responses エンドポイントをサポートしている場合に限られる。

OpenCodeやKilo CodeでOpenAI互換のAIプロバイダを効果的に利用するためには、ベースURLの正確な形式、APIキーの安全な管理、モデルIDの厳密な指定、そして特にコンテキストウィンドウと最大出力トークンを limit ブロックで正しく設定することが不可欠だ。これらの点を注意深く確認し、設定ファイルの記述やエラーメッセージの意味を理解することで、よりスムーズで信頼性の高いAI開発を進めることができるだろう。