このページは英語版ドキュメントの翻訳です。コマンド、識別子、例はそのままです。ランタイム 7.24.4 · SDK 2.6.7。英語版

ローカルエンジン連携（AX Code）

状態: 有効

範囲: 現行状態

最終確認: 2026-09-19

担当: ax-code runtime

ローカルランタイムの準備

/connect で AX-Engine ランタイム を選び、次に モデルを選択 してください。AX Code はローカルランタイムを構成し、選んだモデルが必要になったときに起動します。エンドポイント URL や API キーのフォームはありません。状態を表示、ローカルランタイムを停止（実行中のとき）、無効化 がローカルプロセスを管理します。

AX Code は AX Engine に サイドカー HTTP バックエンドを使います。ax-engine serve を起動し、所有するプロセスを追跡し、ループバックのアドレスとポートを自動で解決します。利用者がモデルを選び、AX Code がトランスポート構成を扱います。

AX Code (TypeScript)
  -> select local model -> ensure/prepare -> spawn ax-engine serve
  -> managed loopback /v1 -> @ai-sdk/openai-compatible language model

モデルを明示的に選ぶと、管理されたライフサイクルが保存され、レガシーの接続用エンドポイントとキー設定が消えます。残っている AX_ENGINE_HOST の値も上書きします。古い SDK クライアントは、レガシーのループバック専用接続 API とその資格情報検証を保ちます。その互換経路はプロバイダーメニューの一部ではありません。

AX Code は AX Engine SDK をプロセス内でリンクしません。モデル実行を所有するのは AX Engine であり、クライアント側のプロセスライフサイクルを所有するのは AX Code です。ホストの適格性、モデルの準備、ライブのツール呼び出し検査は、引き続き適用されます。

コールドスタートの準備完了期限は 600 秒です。起動時間はモデルサイズ、ストレージのスループット、利用可能なメモリに依存します。起動が尽きたターンは、サーバーログとモデルパスとともに停止します。AX Code は別のコールドロードを自動で再起動せず、プロバイダーも切り替えません。明示的に再試行する前に、報告された問題を解決してください。モデル準備の包みは、ライフサイクルロックの待機と能力の発見を含め、660 秒に制限されます。期限が切れると保留中の準備は取り消され、自動再試行は止まります。リクエストを取り消すと、準備の依存先がまだ応答していなくても、待機は直ちに止まります。準備完了期限の後、または所有プロセスが終了した後に届くヘルス応答は、準備完了を確立できません。

準備ができると、エンジンは会話のターンをまたいで常駐します。開始したターンが完了または取り消されても、準備済みエンジンは止まりません。起動がまだ進行中に取り消すと、その試行は終了し、プロセス記録は削除されます。常駐エンジンを明示的に止めるには ローカルランタイムを停止 を使ってください。

AX Code は標準の Hugging Face キャッシュ位置に従い、ローカルディスク、SMB、NFS マウントを含む利用者のストレージ選択を尊重します。キャッシュの解決順は HF_HUB_CACHE、次に HF_HOME/hub、次に XDG_CACHE_HOME/huggingface/hub、次に ~/.cache/huggingface/hub です。明示的に構成された、またはすでに準備されたモデルパスは、キャッシュ探索より優先します。AX Code は重みを移さず、ストレージ種別を理由にこれらの選択を上書きしません。起動診断は実際のモデルパスを報告するので、選んだストレージの可用性と読み取り性能を調べられます。

既存のエンジンに対して、AX Code は最大 3 回のヘルス探査を行います。各探査は 2 秒に制限され、250 ミリ秒間隔です。その後、応答しないプロセスを再起動します。リクエストを取り消すと、既存のプロセスは保たれます。

サイドカーを使う理由

要因	サイドカーの選択
ホスト言語	Node/Bun のエージェントランタイム。明示的なネイティブプロセス境界を持ちます
隔離	数 GB のモデルとネイティブのクラッシュは、エージェントプロセスの外に留まります
アップグレード	バージョンで門をかけた同梱の下限に加え、任意の管理オーバーレイ。ax-code の再ビルドは不要です
プロバイダーモデル	他のローカルおよびクラウドプロバイダーと同じ OpenAI 互換の経路
複数クライアント	1 つのサーバーを `server.json` 経由でヘルスチェックし、停止できます

ライフサイクルのフェーズ

実装: packages/ax-code/src/provider/ax-engine/lifecycle.ts

フェーズ	いつ（AX Code の対応）
`unavailable`	プラットフォームの適格性に失敗
`missing_dependency`	バイナリがない / バージョンが古すぎる / 実行できない
`missing_model`	モデルパスが未準備
`starting`	サーバープロセスは記録されたが、まだ準備できていない
`ready`	`server.ready` とプロセスヘルスが正常
`degraded`	準備はできたが、能力検査が toolcall 非対応と述べる
`error`	実行中の試行におけるヘルスまたは起動失敗の阻害

重大度の順序は ax-engine の docs/LOCAL-ENGINE-CLIENTS.md と一致します。

領域	パス
サーバー起動 / ヘルス	`packages/ax-code/src/provider/ax-engine/server.ts`
プロバイダーローダー（管理と接続）	`packages/ax-code/src/provider/ax-engine/provider-loader.ts`
TUI のローカルランタイム	`packages/ax-code/src/cli/tui/component/dialog-provider.tsx`
ローカル操作の補助	`packages/ax-code/src/cli/tui/component/dialog-provider-options.ts`
集約ステータス	`packages/ax-code/src/provider/ax-engine/status.ts`
フェーズ対応	`packages/ax-code/src/provider/ax-engine/lifecycle.ts`
モデル方針	AX Engine のモデル選択

ピンされたサイドカーの管理プロビジョニングは、プロセス内埋め込みではありません。Darwin-arm64 のリリースは CLI の隣に engine/<version>/ を配置します。ax-code providers ax-engine install は、より新しいピンが公開されたときのオーバーレイ兼アップデーターです。

対象外

AX Code でサイドカーをプロセス内 SDK 埋め込みに置き換えること
gRPC を主要なチャットトランスポートとして採用すること
ファーストパーティのクライアント向けに、独自の Unix ソケットや非 OpenAI のチャットフレーミングを作ること
モデルの重みを AX Code インストーラーに焼き込むこと

ローカルエンジン連携（AX Code）

ローカルランタイムの準備

サイドカーを使う理由

ライフサイクルのフェーズ

関連コード

対象外