AIエージェント入門

Claude Code Remote Control｜ヘッドレス実行入門

14分で読める

この記事の結論

Claude CodeのRemote Control機能。ヘッドレス実行・API制御・CI/CD統合のコード例。

「ノートPCを閉じたら作業が中断する」——これが、Claude Codeを本格的に使い始めた開発者が最初にぶつかる壁でした。

去年末、長時間かかるリファクタリング作業を走らせたまま外出したとき、進捗確認のためにわざわざPCを開く必要があって、正直かなり不便でした。そこで調べてみたのがRemote Control機能です。スマホから確認・指示できるというので試してみると、これが想像以上に実用的でした。

この記事では、Claude CodeのRemote Control機能を徹底解説します。スマホからローカル環境を操作する方法、ヘッドレス実行（-pフラグ）、CI/CDパイプラインへの統合まで、コピペ可能なコード例とともに紹介します。

Remote ControlはClaude Code v2.1.51以降で利用可能です。まず動かしてみましょう。

即効テクニック1：サーバーモードで起動する

# バージョン確認（v2.1.51以上が必要）
claude --version

# プロジェクトディレクトリに移動してサーバーモード起動
cd ~/my-project
claude remote-control

起動すると、セッションURLとQRコードが表示されます。

Remote Control active
Session: https://claude.ai/code/sessions/myhost-graceful-unicorn
Press [Space] to show QR code for mobile

Connected devices: 0 | Sessions: 0/32

スマホでQRコードをスキャン（またはURLを開く）するだけで、ローカルのClaude Codeセッションをスマホから操作できます。

動作環境: Claude Code v2.1.51+、Pro/Max/Team/Enterpriseプラン（APIキー不可）

即効テクニック2：既存セッションをリモート化する

すでに作業中のセッションをリモート対応にするには、セッション内で /rc コマンドを使います。

# 作業中のセッション内で実行
/remote-control "リファクタリング作業"

# または短縮形
/rc "リファクタリング作業"

これで現在の会話履歴を引き継いだまま、スマホから続きを確認・指示できます。

即効テクニック3：全セッション自動リモート対応にする

毎回コマンドを打つのが面倒なら、設定で自動化できます。

# Claude Code内で設定を変更
/config
# "Enable Remote Control for all sessions" を true に設定

この設定をオンにすると、Claude Codeを起動するたびに自動でリモート接続可能になります。

Remote Controlの主要オプションと使い分け

起動方法 コマンド 特徴 最適な用途
サーバーモード claude remote-control 複数セッション対応（最大32） 長時間タスク・チーム共有
インタラクティブ claude –remote-control ローカルとリモート同時操作可 移動中も確認したい通常作業
既存セッション /rc または /remote-control 会話履歴を引き継ぐ 急に外出する必要が生じた時
VS Code /remote-control（プロンプト欄） ブラウザで即確認可能 VS Code利用者の外出先確認

AIエージェントの構築パターン全般についてはAIエージェント構築完全ガイドを参照してください。

ヘッドレス実行：スクリプト・CI/CDへの統合

Remote Controlとは別に、Claude CodeをコマンドラインスクリプトやCI/CDパイプラインに組み込む「ヘッドレスモード」があります。-pフラグがその入口です。

-pフラグ：1プロンプト実行して終了

# 単一プロンプトを実行して終了（ヘッドレスモード）
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
claude -p "package.jsonの依存関係を確認して、セキュリティ上のリスクがある場合は報告してください"

# 許可するツールを明示的に指定（CI/CD推奨）
claude -p "テストを実行してください" 
  --allowedTools "Bash(npm test:*),Read,Grep"

# 出力をJSONで受け取る（パイプライン連携向け）
claude -p "プロジェクトの構造を分析して" --output-format json | jq '.result'

重要: ヘッドレスモードでは通常ユーザー承認が必要なツール呼び出しがブロックされます。--allowedTools で使用ツールを明示的に宣言してください。

GitHub Actionsへの統合

# .github/workflows/claude-code-review.yml
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  code-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Code Review
        env:
          # APIキーではなくOAuthトークンを使用（Remote Control要件）
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
        run: |
          # 変更ファイルを取得
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)

          # Claude Codeでレビュー実行
          claude -p "以下のファイルをレビューしてください: $CHANGED_FILES
          - セキュリティリスクを指摘してください
          - パフォーマンスの問題があれば教えてください
          - 改善提案を具体的に示してください" 
            --allowedTools "Read,Grep,Bash(git diff:*)" 
            --output-format json > review.json

          # PRにコメントを投稿
          REVIEW_CONTENT=$(cat review.json | jq -r '.result')
          gh pr comment ${{ github.event.number }} --body "$REVIEW_CONTENT"
        env:
          GH_TOKEN: ${{ github.token }}

マルチマシン並列実行パターン

一つのオーケストレーターが複数のClaude Codeインスタンスにタスクを分配するパターンです。

# 複数ディレクトリを並列でリファクタリング
# 動作環境: Python 3.11+
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。

import subprocess
import asyncio
import os

async def run_claude_on_directory(directory: str, task: str) -> dict:
    """指定ディレクトリでClaude Codeをヘッドレス実行"""
    cmd = [
        "claude", "-p", task,
        "--allowedTools", "Read,Grep,Edit,Write",
        "--output-format", "json"
    ]

    proc = await asyncio.create_subprocess_exec(
        *cmd,
        cwd=directory,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
        env={**os.environ}
    )

    stdout, stderr = await proc.communicate()

    return {
        "directory": directory,
        "exit_code": proc.returncode,
        "result": stdout.decode() if proc.returncode == 0 else None,
        "error": stderr.decode() if proc.returncode != 0 else None
    }

async def parallel_refactor(directories: list[str], task: str) -> list[dict]:
    """複数ディレクトリを並列処理"""
    tasks = [run_claude_on_directory(d, task) for d in directories]
    results = await asyncio.gather(*tasks)
    return results

# 使用例
async def main():
    dirs = ["./services/auth", "./services/payment", "./services/notification"]
    task = "TypeScriptの型定義を確認し、any型を適切な型に置き換えてください"

    results = await parallel_refactor(dirs, task)

    for r in results:
        status = "SUCCESS" if r["exit_code"] == 0 else "FAILED"
        print(f"[{status}] {r['directory']}")

asyncio.run(main())

セキュリティモデルを理解する

Remote Controlを安全に使うために、通信の仕組みを正確に理解しておきましょう。

項目 詳細
通信方向 ローカルPCからAnthropicAPIへのアウトバウンドHTTPSのみ。インバウンドポートは開かない
ファイルの保存場所 コードはローカルマシンに留まる。チャットメッセージのみがAnthropic経由で転送される
認証 claude.ai OAuthトークン（APIキーは非対応）。短命な複数クレデンシャルを使用
暗号化 全通信はTLSで暗号化（通常のClaude Codeセッションと同等）
Team/Enterprise デフォルト無効。管理者がAdmin Settingsでトグルを有効化する必要あり

【要注意】よくある失敗パターンと回避策

失敗1：APIキーで認証してRemote Controlが使えない

❌ よくある間違い: ANTHROPIC_API_KEY 環境変数を設定してRemote Controlを起動しようとする

⭕ 正しいアプローチ: claude.ai OAuthで認証する

# APIキーをアンセット
unset ANTHROPIC_API_KEY

# OAuthで再認証
claude auth login
# → claude.aiログインオプションを選択

# Remote Control起動
claude remote-control

なぜ重要か: Remote ControlはAnthropicのAPIではなくclaude.aiのOAuthインフラを使用します。APIキー認証では動作しません。

失敗2：ヘッドレスモードでツール呼び出しがブロックされる

❌ よくある間違い: --allowedTools を指定せずに実行し、ツール呼び出しで止まる

# NGパターン: ツール指定なし → 承認待ちでブロック
claude -p "ファイルを読んで分析して"
# → ツール呼び出しが承認待ちになって止まる

⭕ 正しいアプローチ: 必要なツールを明示する

# OKパターン: 使用ツールを明示
claude -p "ファイルを読んで分析して" 
  --allowedTools "Read,Grep,Bash(cat:*)"

なぜ重要か: ヘッドレスモードでは対話的な承認ができません。事前に許可ツールを宣言しないとパイプラインが止まります。

失敗3：ネットワーク断絶でセッションが消える

❌ よくある間違い: ネットワークが不安定な環境でRemote Controlを使い、10分以上切断してセッションが消える

⭕ 正しいアプローチ: 長時間タスクは定期的なチェックポイントを組み込む

# チェックポイント付き長時間タスクの実行例
import subprocess
import time
import json

def run_with_checkpoint(prompt: str, checkpoint_interval: int = 300):
    """5分ごとに進捗を保存する長時間タスク"""

    result = subprocess.run(
        ["claude", "-p", prompt,
         "--allowedTools", "Read,Write,Bash(git:*)"],
        capture_output=True,
        text=True,
        timeout=3600  # 最大1時間
    )

    # 結果をファイルに保存
    with open(f"checkpoint_{int(time.time())}.json", "w") as f:
        json.dump({
            "exit_code": result.returncode,
            "stdout": result.stdout,
            "timestamp": time.time()
        }, f, ensure_ascii=False)

    return result

なぜ重要か: ネットワーク断絶が10分以上続くとセッションが自動終了します。長時間タスクは中間結果をファイルに保存しておくと、再実行時に続きから始められます。

Remote Control vs その他の遠隔操作手段の比較

方法 トリガー Claudeの実行場所 最適な用途
Remote Control claude.aiまたはモバイルアプリ ローカルマシン 進行中の作業を別デバイスで継続
Dispatch Claudeモバイルアプリ ローカルマシン（Desktop） 外出中にタスクを委任
Channels Telegram/Discord/カスタム ローカルマシン CI失敗通知など外部イベントへの対応
スケジュールタスク 時刻 ローカルまたはクラウド 定期的な自動化（日次レポート等）
Slack連携 @Claude メンション Anthropicクラウド PRレビュー・チームコミュニケーション

参考・出典

まとめ：今日から始める3つのアクション

  1. 今日やること: claude --version でv2.1.51以上を確認し、claude remote-control を起動してスマホからアクセスしてみる。QRコードをスキャンするだけで5分で試せます
  2. 今週中: 長時間かかるリファクタリングやテスト実行のときに --remote-control フラグをつけて、外出先から進捗確認する習慣をつける
  3. 今月中: -p フラグと --allowedTools を使ってCI/CDの1ステップをClaude Codeに委任し、コードレビューまたはテスト生成を自動化する

あわせて読みたい:

著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー10万人超。100社以上の企業向けAI研修・導入支援。著書累計3万部突破。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。
ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。

Need help moving from reading to rollout?

この記事を読んで導入イメージが固まってきた方へ

Uravationでは、AIエージェントの要件整理、PoC設計、社内導入、研修まで一気通貫で支援しています。

30分無料相談を予約 支援実績を見る

この記事をシェア

X Facebook LINE

※ 本記事の情報は2026年4月時点のものです。サービスの料金・仕様は変更される可能性があります。最新情報は各サービスの公式サイトをご確認ください。

関連記事

AIエージェント入門

Claude Codeプラグイン開発ガイド｜自作から公開

Claude Codeプラグインの作り方。bin/実行可能ファイル・MCP統合・...

14分で読める
AIエージェント構造化ログ設計｜JSON Lines AIエージェント入門

AIエージェント構造化ログ設計｜JSON Lines

AIエージェントの構造化ログをJSON Linesで設計。PII除去・ログレベル...

15分で読める
MCPサーバー構築｜TypeScript/FastMCP実装 AIエージェント入門

MCPサーバー構築｜TypeScript/FastMCP実装

MCPサーバーをTypeScript SDKとFastMCPで構築。Claude...

15分で読める