Guilduoのトラブルシューティング：接続・権限・保存の診断

401・OAuth復帰・アカウント違い

認証なしでMCPやRESTを開いて401になることは、認証が必要な経路では正常です。ブラウザでURLを開けたことだけで接続成功とは判断しません。

1. MCP URLがhttps://mcp.guilduo.com/mcpか確認します。https://api.guilduo.com/v1はAppwrite APIです。
2. Web AppとOAuth画面で選んだアカウントが一致するか確認します。別アカウントのQuestを見ている可能性があります。
3. 移行前の接続や失効した認可が原因ならOAuthをやり直します。旧GrantやTokenは使い回しません。
4. OAuthから戻れない場合は、callbackを妨げる拡張やクライアントの復帰状態を確認します。

ツールやSkillが見えない

/healthが報告するツール数と、認証済みクライアントが実際に扱えるツールは別の確認です。数の違いだけでAgentの権限を広げません。

1. 必要なツール名を確認します。Human Relayにはrequest_human_reviewとlist_human_requestsが必要です。
2. クライアントの接続メタデータをRefreshし、必要なら再起動して新しいチャットを始めます。
3. Skillの読み込みは別に確認します。Codexのローカルcompanionはインストール済みでも、進行中の会話へ自動追加されたとは限りません。
4. Refreshが失敗したら、クライアント版、見えているツール名、エラーを記録します。動作中の接続をすぐ削除したり重複登録したりしません。

未リンク・読み取り専用・403

409・再送・保存結果不明

• quest_conflict：対象Questを再取得し、最新expectedUpdatedAtで再プレビューします。
• Handoff競合：実際の状態を読み、expectedStateを更新します。すでに承認された仕事を古い状態へ戻しません。
• request_key_conflict：同じkeyに異なる依頼内容が指定されています。既存依頼を確認し、次ラウンドなら新keyを使います。
• human_request_pending：未回答・保留の依頼を再開します。新しいkeyで重複を作りません。
• 保存応答が失われた・5xx：まず再取得します。一般のQuest作成までrequestKeyで冪等になっているとは考えず、保存状態を確かめてから再送を判断します。

再接続と問題報告

同期中は前回データが読み取り専用で残る場合があります。同じアカウントで再接続し、保存済み状態を確認します。単発To Doの完了後はArchiveも確認してください。

公開GitHub Issuesはhttps://github.com/ELRdn/Guilduo/issuesです。下の項目を揃えると、認証・UI・ツール契約のどの問題か判断しやすくなります。

• クライアント名と版、発生日時、期待した動作、実際の結果。
• 失敗したツール名またはREST経路、HTTP status、エラーコード。
• 読み取り・プレビュー・保存のどこで失敗したか、再取得した状態。
• 秘密情報やQuest本文を除いた最小の再現手順。Token、完全なUID、Client IDは公開しません。