OpenCodeでGuilduoを使う

必要な環境

• WindowsのOpenCode 1.18.32／1.18.35で検証しています。OpenCode v2の互換性は未検証です。
• 認証・資格情報の保存はOpenCodeが担当します。プラグイン独自の資格情報保存やトークンbridgeはありません。
• 通常導入で追加のモデル継続は始まりません。phaseSyncは初期状態でOFFです。

opencode.jsonへ追加する

プロジェクトの既存plugin配列に次の項目を追加し、他の設定・プラグインを保持します。導入変更前に、その設定を使うOpenCodeプロセスを終了してください。

1. 再起動するとコンパイル済みコードとSkillを読み込みます。利用者によるビルドは不要です。固定版なら@latestを@0.6.0-beta.16へ置き換えます。
2. 既存の公式endpoint別名、無効化設定、占有済みguilduoキーは保持します。別endpointとの競合は自分のMCP設定で解消してください。

{
  "plugin": [
    "@guilduo/opencode-plugin@latest"
  ]
}

OpenCode標準OAuthで認証する

接続先はhttps://mcp.guilduo.com/mcpです。既存の別名がある場合、コマンドのguilduoをその別名へ置き換えます。ブラウザーで同じGuilduoアカウントを許可し、ホストへ戻ります。callbackや認証ファイルを会話へ貼り付けません。

opencode mcp list
opencode mcp auth guilduo
opencode mcp auth list

Agentと作業権限を確認する

Freeの上限は2登録Agentです。導入・OAuth・AgentリンクはAgent自動登録やQuest継続更新の許可ではありません。guilduo-workflows Skillは許可範囲での作業を案内し、完了・承認・報酬を自動許可しません。接続管理のOAuth権限とAgentの実行scopeは別で、実行権限を広げてリンクエラーを解消しないでください。

1. 最初にget_agent_linkを読み、接続が意図した既存のRegistry Agentに紐付いているか確認します。必要ならlist_registered_agentsで既存の許可済みAgentを調べます。表示名やクライアント名からIDを推測しません。
2. 未リンクの専用接続では、所有者の明示的な許可を得てlink_agentに既存AgentのagentIdを渡します。正しいリンクは維持します。共有接続を別Agentへ切り替えるためにlink_agentを使いません。
3. get_current_agent_contextと対象のget_questを読み、返ったAgent IDとQuest IDを確認します。requiresAgentSelectionがtrueなら、allowedAgentIdsから所有者が許可したactingAgentIdを選び、プレビュー・読み取り・書き込みの各呼び出しで保持します。
4. 更新するQuestと許可する変更を明示してから作業します。対応ツールではdryRunでプレビューし、update_questでは最新のexpectedUpdatedAtを使って狭い変更を送り、再読で保存を確認します。update_questにdryRunは送りません。

読み込みと接続を確認する

--versionはホスト版です。Skill一覧にguilduo-workflowsがあり、MCPの接続状態が正しいことを確認します。その後、対象Agentのcontextと正確なQuestを実際に読みます。認証済み表示やツール発見だけでは読み書きの成功を証明しません。

opencode --version
opencode debug skill
opencode mcp list
opencode mcp auth list

任意：特定会話のphaseSyncを有効にする

継続更新を許可済みのQuest／Agentに限って使います。新しいプロジェクトではまずOFFのままnative sessionを作成し、OpenCodeを完全終了してから、その既存session IDとホストが解決した正確なcwdを設定して再起動します。下記プレースホルダーは実値へ置き換えてください。

• 一致するbuild sessionの完了stop応答とidle後、元のユーザー入力ごとに最大1回の追加モデル確認を行います。provider料金が発生し得ます。MCPへ直接書き込む機能ではありません。
• cwdの大文字小文字を含む正確なbindingが必要です。新規会話・forkへbindingをコピーしません。Plan／読み取り専用、エラー、compaction、不一致、無効MCPでは継続しません。失敗・不明な送信を自動再試行しません。

{
  "plugin": [
    [
      "@guilduo/opencode-plugin@latest",
      {
        "phaseSync": {
          "sessionId": "ses-your-existing-session",
          "questId": "your-quest-id",
          "actingAgentId": "your-allowed-agent-id",
          "cwd": "D:\\your-project"
        }
      }
    ]
  ]
}

更新・停止する

更新時はOpenCodeを終了し、互換性とリリース内容を確認してplugin項目をlatestまたは確認した固定版にします。他の設定を保持して再起動し、Skill・接続・読み取りを再確認します。

現在の推論はOpenCode標準interrupt／abortで止めます。phaseSyncを永続的に止めるには終了後に設定を削除またはfalseにして再起動します。

bindingと未使用のコマンド名がある場合、/guilduo-sync-offでその会話のbindingを次のplugin reloadまで解除できます。別会話には効きません。slash commandはプロンプトを送るため、推論abortや無課金停止の保証ではありません。継続更新の許可とOAuthは別途取り消します。

切断・削除する

npm形式の設定はホストが管理します。明示MCP設定とnative認証はplugin削除だけでは消えません。ローカルarchiveを専用.opencode/guilduoへ導入した場合だけ、その専用prefixから削除します。共有.opencodeでnpm uninstallを実行して他パッケージを巻き込まないでください。

1. 自分の別名でlogoutし、phaseSyncを無効化します。再接続を止める場合は公式MCP entryをenabled: falseで明示的に残します。entryを消すだけではplugin reload時に既定接続が追加されます。
2. サーバー側の認可はhttps://app.guilduo.com/の接続管理で別途失効させます。
3. OpenCodeを終了し、opencode.jsonからこのpluginの文字列／tupleだけを削除します。個別loaderがあればそれも外します。再起動後、Skillとplugin所有commandが消えたことを確認します。

opencode mcp logout guilduo
opencode mcp auth list

検証範囲と公式掲載

Windows 1.18.35では公開OAuth、専用リンク済みAgent／Questの読み取り、限定・version guard付き更新と再読、Human保存回答→同じGo会話での再開、QA 401を契機にした公開refresh、失効・再接続の受入記録があります。phaseSyncの実モデル検査は両ホスト版の合成loopback MCPを使用し、公開phaseSyncの受入とは別です。

OpenCode Ecosystem PR #54271はv1のcritical-fixes-only方針によりclosed・未mergeです。OpenCode公式一覧への掲載は完了していません。共有接続でのcross-Agent選択は未受入です。これらは公開npmからの導入手順と分けて扱います。