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

長時間の作業で AX Code を運用する

ステータス: 現行対象範囲: 現在の状態最終確認: 2026-09-13 所有者: AX Code メンテナー

AX Code は、対話的な Super-Long 実行を 1 回あたり 72 時間に制限します。日単位や週単位で運用する場合は、監視付きの ax-code serve プロセスを動かし、作業を永続的なスケジュール済みの発生へ分割します。監視側がサーバーを再起動し、プロジェクトのデータベースがスケジュールとキューの状態を保持します。

持続する対話ワークスペース

ターミナルを閉じたあともローカル作業を続けたい場合は、プロジェクトのランタイムを明示的に有効にします。

ax-code runtime start --dir /absolute/path/project
ax-code runtime attach --dir /absolute/path/project --continue
ax-code runtime status --dir /absolute/path/project
ax-code runtime list                  # every managed runtime on this machine
ax-code runtime stop --dir /absolute/path/project

runtime attach も、ランタイムが存在しないときは起動します。ランタイムは正規化されたプロジェクトディレクトリをキーにし、同時の起動は 1 つのプロセスを再利用します。TUI には実行ホストと切断アクションが表示されます。切断するとクライアントは閉じますが、受け付け済みの作業は動き続けます。runtime stop はそのプロジェクトのランタイムを停止し、進行中の作業を中断します。通常の ax-code は、既存のフォアグラウンドのライフサイクルを維持します。

セッションが忙しいあいだに送られた、受け付け済みのフォローアップはサーバーに保存されます。既定では、実行中のターンが終わってから開始するため、無関係な要求が進行中の作業を脱線させることはありません。実行中のターンを修正したい場合は、テキストだけの下書きで ctrl+s（input_submit_steer。対象は keybinds）を押します。そのテキストは進行中の生成へ取り込まれ、ループの次のステップ境界でユーザーメッセージとして書き込まれます。これは、飛行中のツール呼び出しが落ち着いたあと、次のモデル要求の前です。ターンが終わりかけているときに取り込まれた修正は、破棄されず、実行を 1 反復だけ延ばします。ステアリングはベストエフォートです。もはや生成が動いていなければ、下書きは通常の経路で送られます。フックが拒否した場合、下書きは理由とともにコンポーザーに残ります。添付ファイル付きの下書きとスラッシュコマンドは、常にフォローアップキューを使います。同じ配送は、ハーネス制御で説明するステアリング API を通じて、他のクライアントからも使えます。保存済みのフォローアップは、事後にステアリングすることもできます。空のコンポーザーで ctrl+s を押すと、キューのうちステアリング可能な先頭部分が順に昇格し、ステアリングできない最初の行で止まります。サイドバーのフォローアップ節と /queue ダイアログにも、行ごとの「今すぐステアリング」があります。一時停止中の行は、その場でステアリングできます。ターンを中断すると、待機中のフォローアップは一時停止し、そのうち 1 件をステアリングすると、キューの残りを再開せずにテキストだけを届けます。障壁になるのは、フォローアップ以外の行（キューされたスラッシュコマンドやシェルコマンド）、添付付きの行、空または過大なテキスト、すでに実行中または完了した行だけです。ステアリングされた行は steeredInto の監査証跡付きで取り消され、/queue の履歴に残ります。生成が動いていないとき、「今すぐステアリング」はその行をキューの先頭へ優先する動作に戻ります。それでも開始するのは、ターンが終わったあとです。コンポーザーがクリアされるのは、確認応答のあとだけです。同じセッションへ再接続し、/queue で検査、一時停止、編集、再開、取り消しができます。編集はまず項目を一時停止し、添付とモデル選択を保持します。保存しても再開はしません。同時に起きた古い編集は拒否されます。/queue では、Ctrl+R に完了と取り消しの履歴が含まれます。狭いターミナルでは、クリックできる Follow-ups 見出しも表示されます。切断されたビューはキャッシュされており、項目を変更できません。実行中のターンを中断すると、保留中のフォローアップは一時停止し、すぐに次のターンを始めません。準備ができたら明示的に再開してください。

バックエンドの再起動後、受け付け済みで待機中のフォローアップは再開できます。その再起動で中断された、通常の飛行中プロンプトは失敗として印が付き、再試行の前に検査が必要です。キュー記録を復元しても、実行中だったシェルプロセスは復元されません。確認応答が失われた場合は、そのクライアントセッションのあいだ、同じ要求 ID で、変更していないコンポーザーから再試行できます。未保存の下書きは受け付け済みのジョブではなく、外部副作用がちょうど 1 回だけ起きることは保証しません。

このモードは、ログインサービスをインストールせず、クラッシュしたサーバーを自動再起動せず、ホストがスリープ中や電源オフのあいだは実行しません。クラッシュ後は、再度起動するか接続してください。無人のサーバー再起動には、下記の監視付きサービス例を使います。SSH の利用者は、起動したままのリモートホストでランタイムを動かし、そこに接続してください。HTTP ポートを公開しないでください。

ランタイムの検出は、AX Code 状態ディレクトリの runtime/ フォルダに、非公開のケイパビリティとログを保存します。ステータス出力にはケイパビリティを含めません。停止には、保存された PID だけではなく、認証済みで一致するランタイム ID が必要です。ライブプロセスが使えない、記録が壊れている、またはバージョンが一致しない場合は検査が必要です。CLI は、検証されていないプロセスの強制終了を拒否します。アップグレードの前に正常なランタイムを停止し、新しい実行ファイルで再起動してください。

信頼性モデル

事象	挙動
期限到来の発生が確定する前にバックエンドが終了した	その発生は期限到来のまま残る
スケジュールからキューへのトランザクション確定後にバックエンドが終了した	同じキュー項目が起動時に再開される
プロンプト開始後にバックエンドが終了した	中断された項目は、自動再送されず失敗として記録される
ホストが複数の発生を逃した	`run_once` はそれらを 1 回の実行へまとめ、`skip` は実行せずに進む
キューの実行が期限を超えた	実行側がセッションを取り消し、失敗したキュー項目を記録する
監視側がサーバー終了を検知した	下記の例は、短い遅延のあと再起動する

これは重複に安全な回復であり、任意の外部副作用に対する厳密な 1 回配送ではありません。外部システムへ書き込む連携は、引き続き独自の冪等キーを使うべきです。

サービスを入れる前に

サービスを動かすのと同じユーザーで、ax-code 実行ファイルをインストールして試します。
絶対パスのプロジェクトを 1 つ選びます。それを AX_CODE_PROJECT に設定し、サーバー起動時にそのプロジェクトを事前準備してスケジューラを開始します。
サーバーは 127.0.0.1 に置きます。AX Code のサーバーはローカル専用です。
プロバイダーの認証情報は、コミットされるサービスファイルではなく、監視側の保護された環境に置きます。
選んだ例にある /absolute/path/... プレースホルダーをすべて置き換えます。

例は固定ポートを使うため、Desktop または SDK のクライアントが再接続できます。

ax-code serve --hostname=127.0.0.1 --port=4096

systemd のユーザーサービス

systemd の例を ~/.config/systemd/user/ax-code.service へコピーし、絶対パスを置き換え、必要なら認証情報を ~/.config/ax-code/server.env に置きます。

chmod 600 ~/.config/ax-code/server.env
systemctl --user daemon-reload
systemctl --user enable --now ax-code.service
systemctl --user status ax-code.service
journalctl --user -u ax-code.service -f

ユーザーがログアウトしていてもユーザーサービスを動かすことを運用方針が許す場合に限り、loginctl enable-linger "$USER" を使います。

launchd エージェント

launchd の例を ~/Library/LaunchAgents/com.axcode.server.plist へコピーし、絶対パスを置き換えてから、検証して読み込みます。

plutil -lint ~/Library/LaunchAgents/com.axcode.server.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.axcode.server.plist
launchctl kickstart -k "gui/$(id -u)/com.axcode.server"

launchd は ProgramArguments 内のシェル変数を展開しません。絶対パスを使い、必要な認証情報は運用者が管理する仕組みで渡してください。

PM2 での運用

PM2 の例をコピーし、パスを置き換えて起動します。

pm2 start docs/examples/ax-code-ecosystem.config.cjs
pm2 save
pm2 logs ax-code-server

ホスト再起動後にもプロセスを戻す必要がある場合は、PM2 のプラットフォーム別の起動手順に従ってください。

期限、追いつき、回復

スケジュールタスクの既定は catchUpPolicy: "run_once" です。停止時間のあと、AX Code は無制限の積み残しを作らず、まとめられた発生を 1 回実行します。遅れた作業が誤解を招く、または危険な場合は "skip" を選びます。

各スケジュールタスクは、maxRunDurationMs を 1 秒から 72 時間の範囲で設定できます。それ以外のタスクキュー実行は、72 時間の上限を使います。実行中の項目は 30 秒ごとにハートビートのタイムスタンプを更新し、終端ステータスとエラー詳細はプロジェクトのデータベースに残ります。

非同期のプロンプト、コマンド、シェルのエンドポイントは、HTTP 202 応答で永続的なキュー項目を返します。クライアントはその id を保持し、GET /task-queue/:id を、completed、failed、または cancelled になるまでポーリングするべきです。受け付けだけでは完了ではありません。

起動時、永続的な AX Code バックエンドは、確定済みでまだ開始していなかったスケジュールキュー項目と、明示的に非同期と印が付いた項目を再開します。ワンショットの CLI コマンドは、それらの項目の所有権を取りません。すでに開始していたプロンプト作業は、再起動の説明付きで失敗となり、オペレーターが副作用を検査してから再試行できます。

スケジュールタスクが何をしているかを見る

スケジュールタスクの各発生は、起きているあいだ見え、あとから監査できます。

開始、完了、失敗、スキップ、および永続的な失敗による自動一時停止は、それぞれタスク名を含むアプリ内通知を出します。
/schedule の TUI コマンドは、すべてのタスクをステータス、スケジュール、次回実行時刻、最後のエラーとともに一覧し、最近の実行履歴を開きます。そこから一時停止、再開、今すぐ実行、削除（確認するには ctrl+d を 2 回押す）、実行が作ったセッションへの移動ができます。エージェントの list_scheduled_tasks と list_scheduled_task_runs ツールは、同じ質問に会話で答えます。
各実行は、タスクのタイトルが付いた新しいセッションで行われるため、通知を見逃しても、セッション一覧から 1 件たどれば結果に着きます。
別の会話を見ているあいだに、実行が許可や質問への回答を求めた場合、警告が、あなたを必要とするセッション名を示します。/attention は既知の保留要求を一覧し、要求元のセッションを開きます。要求には、そのセッション、または読み込み済みの祖先のビュー（子セッションと孫セッションを含む）で答えられます。要求を開いても、自動では承認されません。
1 回限りのタスクが無効になるのは、成功した実行のあとだけです。失敗した発生は上限付きのバックオフで再試行し、失敗が繰り返されると通知付きでタスクを一時停止します。リマインダーが黙って消えることはもうありません。

運用上の確認

監視側の再起動回数とサーバーログを監視します。
再試行の前に、失敗したタスクキュー項目とスケジュールタスクのエラーを検査します。
プロジェクトの SQLite データベースとログに十分なディスク容量があることを確認します。
認証情報、モデル、サービスパスを変えたあとは、手動の 今すぐ実行 を試します。
監視側を通じて停止し、AX Code が SIGTERM を受け取れるようにします。例では、穏やかな停止に最大 90 秒を許します。

/loop は意図的にプロセス内だけで、再起動を生き延びません。無人で永続する作業にはスケジュールタスクを使います。

並列セッションを移動する

端末の列数が 146 以上のとき、左のナビゲーションサイドバーに、現在のワークスペースのセッションと、読み込み済みの子エージェントが表示されます。行の + コントロールで展開し、タイトルをクリックして開きます。ピン留めしたセッションは順序とショートカット番号を保ちます。完全な活動ラベルは、作業中、再試行中、承認、質問を区別します。親は子孫からの要求も反映します。これらのラベルは、タスクが検証に合格したことを意味しません。既存の右サイドバーは、現在のセッションの文脈とコントロールを保ちます。

プロジェクト見出しは現在のディレクトリを示します。クリックするか /navigation-info を使うと、プロジェクトの完全なパスと現在のセッションタイトルが見えます。最近は読み込み済みセッションを示し、アクティブは作業中または待機中のセッション木と、現在のセッション木を保ちます。フィルタはナビゲーションピッカーと共有され、記憶されます。キーボードから切り替えるには /navigation-filter を使います。切断中は、どのセッションがアクティブかを推測せず、キャッシュされたセッションを表示します。クリア（または /navigation-clear）は確認を求めたあと、左レールとナビゲーションピッカーからのみ履歴行を隠します。セッションは削除しません。/sessions は引き続きそれらを一覧します。現在のセッション木、ピン留めしたセッション、観測された作業中または待機中の木はレールに残ります。/sessions からセッションを開くと、一覧へ戻ります。

/navigation-width、またはナビゲーションの幅アクションで、20、24、28、30、32、36、40 列を選べます（既定は 28）。右のセッションサイドバーにも同じ幅アクションと /sidebar-width があります（既定は 32）。どちらの設定も記憶され、メインコンテンツを守る必要があるときは自動で縮みます。広い端末で左のナビゲーションレールを隠す、または戻すには /navigation を使います。/sidebar は、同じ方法で右のセッションサイドバーを隠す、または戻します。より狭い端末では、/navigation がセッションとエージェントのピッカーを開きます。ナビゲーションレールがないときはいつでも、見えるセッションバーが同じアクションを提供します。既知の要求が入力を必要とするとき、その保留アクションが現れます。切断中は、キャッシュされた件数にアスタリスクが付きます。/sessions は引き続き通常のセッションピッカーを開きます。/attention はどの幅でも使えます。切断中、その一覧はキャッシュ済みと表示されます。キャッシュされた項目は開けますが、要求は別の場所ですでに答えられていることがあります。サイドバーの既知の要求アクションは、既知のワークスペースを横断する保留要求を開き、セッション木は現在のプロジェクトに限定されたままです。これらのビューはすべて、接続中のインスタンスと読み込み済みのセッションデータに限られます。この件数は、他のサーバーや未読み込みワークスペースの完全な目録ではありません。

未送信の下書きは、実行中の TUI の中で、プロジェクトとセッションごとに隔離されます。セッションを切り替えると、テキスト、添付、カーソル位置、シェルモードが保たれ、戻ると対応する下書きが復元されます。これらの下書きはメモリ上だけで、TUI を閉じると残りません。

任意の完了通知は、今は Session idle と告げます。見ているセッション部分木で観測された作業に従い、観測されたアクティブな子孫が明示的にアイドルになり、保留要求がなくなるまで待ちます。切断、再同期、状態の欠落、エラー、取り消しは、通知を抑止することがあります。これはライフサイクルの通知であり、テストが合格したことやゴールが完了したことの証拠ではありません。

新しいタスクとセットアップ

通常の起動は、下部コンポーザーとセッションナビゲーションを備えた新規タスクの作業面を開きます。それを開くことや下書きを入力することは、保存されたセッションを作りません。セッションが作られるのは送信したときです。既存の作業を再開するには /sessions か左のナビゲーションを使います。明示的な --session、--continue、--prompt の挙動はそのまま使えます。起動時に自動再開は有効になりません。

プロバイダーのセットアップは自動では開きません。プロバイダーが未設定のときは、作業領域に見える /connect アクションを使います。プロバイダーは設定されているが有効なモデルが選ばれていない場合、アクションは /models に変わります。プロバイダー検出の失敗は /status を指します。設定を修復するには /connect と /providers が引き続き使えます。選ばれたモデルは設定上の選択であり、認証情報やランタイム準備の確認ではありません。設定に注意が必要な再訪ユーザーにも、同じヒントが表示されます。