opencode-acp-control

OpenCode ACP スキル

Agent Client Protocol（ACP）を介して OpenCode を直接操作します。

メタデータ

• ACP プロトコルのドキュメント（エージェント／LLM 向け）：https://agentclientprotocol.com/llms.txt
• GitHub リポジトリ：https://github.com/bjesuiter/opencode-acp-skill
• このスキルで問題が発生した場合は、こちらからイシューチケットを作成してください：https://github.com/bjesuiter/opencode-acp-skill/issues

クイックリファレンス

操作	方法
OpenCode を起動	bash(command: "opencode acp --cwd /path/to/project", background: true)
メッセージを送信	process.write(sessionId, data: "<json-rpc>\n")
応答を読み取る	process.poll(sessionId) - 2 秒ごとに繰り返します
OpenCode を停止	process.kill(sessionId)
セッションを一覧表示	bash(command: "opencode session list", workdir: "...")
セッションを再開	セッションを一覧表示 → ユーザーに確認 → session/load
バージョンを確認	bash(command: "opencode --version")

OpenCode の起動

bash(
  command: "opencode acp --cwd /path/to/your/project",
  background: true,
  workdir: "/path/to/your/project"
)

返された sessionId を保存してください。以降のすべてのコマンドで必要になります。

プロトコルの基本

• すべてのメッセージは JSON-RPC 2.0 形式です
• メッセージは 改行区切り です（それぞれの末尾に \n を付けます）
• 0 から始まる メッセージ ID カウンター を維持します

ステップごとのワークフロー

ステップ 1：接続を初期化する

OpenCode の起動直後に送信します。

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true},"terminal":true},"clientInfo":{"name":"clawdbot","title":"Clawdbot","version":"1.0.0"}}}

応答をポーリングします。result.protocolVersion: 1 が返される想定です。

ステップ 2：セッションを作成する

{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/path/to/project","mcpServers":[]}}

応答をポーリングします。result.sessionId（例："sess_abc123"）を保存します。

ステップ 3：プロンプトを送信する

{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"sess_abc123","prompt":[{"type":"text","text":"Your question here"}]}}

2 秒ごとにポーリングします。次の内容を受け取ります。

• session/update 通知（ストリーミングされるコンテンツ）
• result.stopReason を含む最終応答

ステップ 4：応答を読み取る

ポーリングごとに複数行が返される場合があります。各行を JSON として解析します。

• 通知：method: "session/update" - 応答に含めるために収集します
• 応答：リクエストと一致する id を含みます。stopReason が現れたらポーリングを停止します

ステップ 5：キャンセルする（必要な場合）

{"jsonrpc":"2.0","method":"session/cancel","params":{"sessionId":"sess_abc123"}}

応答はありません。これは通知です。

追跡する状態

OpenCode のインスタンスごとに、次の項目を追跡します。

• processSessionId - bash ツールから取得（clawdbot のプロセス ID）
• opencodeSessionId - session/new の応答から取得（OpenCode のセッション ID）
• messageId - 送信するリクエストごとにインクリメント

ポーリング戦略

• 2 秒ごとにポーリングします
• stopReason を含む応答を受け取るまで続けます
• 最大待ち時間：5 分（150 回のポーリング）
• 応答がない場合は、操作がタイムアウトしたと判断します

一般的な停止理由

stopReason	意味
end_turn	エージェントの応答が完了しました
cancelled	プロンプトをキャンセルしました
max_tokens	トークン上限に達しました

エラー処理

問題	解決方法
ポーリング応答が空	ポーリングを続けます。エージェントが処理中です
解析エラー	形式が不正な行をスキップして続行します
プロセスが終了した	OpenCode を再起動します
5 分経っても応答がない	プロセスを終了して、新たに開始します

例：一連のやり取り

1. bash(command: "opencode acp --cwd /home/user/myproject", background: true, workdir: "/home/user/myproject")
   -> processSessionId: "bg_42"

2. process.write(sessionId: "bg_42", data: '{"jsonrpc":"2.0","id":0,"method":"initialize",...}\n')
   process.poll(sessionId: "bg_42") -> initialize response

3. process.write(sessionId: "bg_42", data: '{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/home/user/myproject","mcpServers":[]}}\n')
   process.poll(sessionId: "bg_42") -> opencodeSessionId: "sess_xyz789"

4. process.write(sessionId: "bg_42", data: '{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"sess_xyz789","prompt":[{"type":"text","text":"List all TypeScript files"}]}}\n')
   
5. process.poll(sessionId: "bg_42") every 2 sec until stopReason
   -> Collect all session/update content
   -> Final response: stopReason: "end_turn"

6. When done: process.kill(sessionId: "bg_42")

---

セッションを再開する

利用可能なセッションからユーザーに選んでもらい、以前の OpenCode セッションを再開します。

ステップ 1：利用可能なセッションを一覧表示する

bash(command: "opencode session list", workdir: "/path/to/project")

出力例：

ID                                  Updated              Messages
ses_451cd8ae0ffegNQsh59nuM3VVy      2026-01-11 15:30     12
ses_451a89e63ffea2TQIpnDGtJBkS      2026-01-10 09:15     5
ses_4518e90d0ffeJIpOFI3t3Jd23Q      2026-01-09 14:22     8

ステップ 2：ユーザーに選択してもらう

一覧をユーザーに提示し、どのセッションを再開するか尋ねます。

"Which session would you like to resume?
 
1. ses_451cd8ae... (12 messages, updated 2026-01-11)
2. ses_451a89e6... (5 messages, updated 2026-01-10)
3. ses_4518e90d... (8 messages, updated 2026-01-09)

Enter session number or ID:"

ステップ 3：選択したセッションを読み込む

ユーザーが応答したら（例：「1」、「最初のもの」、「ses_451cd8ae...」）、次の手順を実行します。

1. OpenCode ACP を起動する：

   bash(command: "opencode acp --cwd /path/to/project", background: true, workdir: "/path/to/project")
   

2. 初期化する：

   {"jsonrpc":"2.0","id":0,"method":"initialize","params":{...}}
   

3. セッションを読み込む：

   {"jsonrpc":"2.0","id":1,"method":"session/load","params":{"sessionId":"ses_451cd8ae0ffegNQsh59nuM3VVy","cwd":"/path/to/project","mcpServers":[]}}
   

注：session/load には cwd と mcpServers のパラメーターが必要です。

読み込み時に、OpenCode は会話履歴全体をストリーミングして返します。

セッション再開ワークフローの概要

function resumeSession(workdir):
    # List available sessions
    output = bash("opencode session list", workdir: workdir)
    sessions = parseSessionList(output)
    
    if sessions.empty:
        notify("No previous sessions found. Starting fresh.")
        return createNewSession(workdir)
    
    # Ask user to choose
    choice = askUser("Which session to resume?", sessions)
    selectedId = matchUserChoice(choice, sessions)
    
    # Start OpenCode and load session
    process = bash("opencode acp --cwd " + workdir, background: true, workdir: workdir)
    initialize(process)
    
    session_load(process, selectedId, workdir, mcpServers: [])
    
    notify("Session resumed. Conversation history loaded.")
    return process

重要な注意事項

• 履歴の再生：読み込み時に、過去のメッセージがすべてストリーミングされます
• メモリの保持：エージェントは会話全体を記憶しています
• プロセスから独立：セッションは OpenCode を再起動しても維持されます

---

OpenCode の更新

OpenCode は再起動時に自動更新されます。更新を確認して適用するには、このワークフローを使用します。

ステップ 1：現在のバージョンを確認する

bash(command: "opencode --version")

次のような結果が返されます：opencode version 1.1.13

バージョン番号（例：1.1.13）を抽出します。

ステップ 2：最新バージョンを確認する

webfetch(url: "https://github.com/anomalyco/opencode/releases/latest", format: "text")

リダイレクト先の URL に最新のバージョンタグが含まれています：

• リダイレクト先：https://github.com/anomalyco/opencode/releases/tag/v1.2.0
• URL パスからバージョンを抽出します（例：1.2.0）

ステップ 3：比較して更新する

最新バージョンが現在のバージョンより新しい場合：

1. 実行中のすべての OpenCode プロセスを停止します：

   process.list()  # Find all "opencode acp" processes
   process.kill(sessionId) # For each running instance
   

2. インスタンスを再起動します（OpenCode は起動時に新しいバイナリを自動ダウンロードします）：

   bash(command: "opencode acp --cwd /path/to/project", background: true, workdir: "/path/to/project")
   

3. 各インスタンスを再初期化します（既存のセッションの場合は initialize と session/load を実行します）

ステップ 4：更新を確認する

bash(command: "opencode --version")

バージョンが最新のものと一致しない場合：

• ユーザーに伝えます：「OpenCode の自動更新に失敗した可能性があります。現在：X.X.X、最新：Y.Y.Y」
• 手動での更新を提案します：curl -fsSL https://opencode.dev/install | bash

更新ワークフローの概要

function updateOpenCode():
    current = bash("opencode --version")  # e.g., "1.1.13"
    
    latestPage = webfetch("https://github.com/anomalyco/opencode/releases/latest")
    latest = extractVersionFromRedirectUrl(latestPage)  # e.g., "1.2.0"
    
    if semverCompare(latest, current) > 0:
        # Stop all instances
        for process in process.list():
            if process.command.includes("opencode"):
                process.kill(process.sessionId)
        
        # Wait briefly for processes to terminate
        sleep(2 seconds)
        
        # Restart triggers auto-update
        bash("opencode acp", background: true)
        
        # Verify
        newVersion = bash("opencode --version")
        if newVersion != latest:
            notify("Auto-update may have failed. Manual update recommended.")
    else:
        notify("OpenCode is up to date: " + current)

重要な注意事項

• セッションは保持されます：opencodeSessionId は再起動後も維持されます。復元するには session/load を使用してください
• 自動更新：OpenCode は再起動時に新しいバイナリを自動ダウンロードします
• データ損失なし：会話履歴はサーバー側に保持されます