Claude Codeを「質問に答えるツール」ではなく「常時稼働するエージェント基盤」として使うには、セットアップと設定の設計が欠かせません。

この記事では、開発者向けコンテンツクリエイターCyrilXBTが紹介するClaude Agent OSの考え方を軸に、ローカル環境の構築から最初のエージェント実行、常時稼働化までの手順を整理します。

この記事でわかること

  • Claude Agent OSが何を指し、コーディング支援との違いは何か
  • Claude CodeのインストールとAPIキー設定の手順
  • CLAUDE.mdとスキルでエージェントの振る舞いを固定する方法
  • OSSのClaude Agent OSを使った常時稼働エージェントの起動手順

Claude Agent OSとは何か

Claude Agent OSは、Anthropicのターミナル型AIツール「Claude Code」を中核に、記憶・タスク管理・定期実行・外部チャネル連携を組み合わせた「個人用エージェント基盤」を指す呼び方です。単発のコード生成ではなく、プロジェクト文脈を保持したまま自律的に作業を進める運用を前提にします。

CyrilXBTは2026年6月の投稿で、多くの人が試行錯誤に数週間かける設定を「セットアップ、設定、最初のエージェント実行、実務で効くワークフロー」に絞って20分で押さえられると紹介しています。ここでいうAgent OSは、特定の1製品名というより「Claude CodeをエージェントOSとして使うための構成一式」を意味します。

同名のOSSも存在します。GitHubのtravis-burmaster/claude-telegram-agentはプロジェクト名を「Claude Agent OS」とし、メモリ・タスク・Cron・Web UI・Telegram連携を備えた常時稼働エージェントを提供します。VPS向けにはtry-agent-os/claude-agent-os（旧称claude-code-template）があり、Telegramボット経由でClaude Codeをサーバー上で24時間稼働させるテンプレートです。

課題：コーディング支援のままではエージェントにならない

Claude Codeを関数生成のために開いて閉じる使い方では、毎回コンテキストがリセットされ、自律的な開発フローには乗りません。CyrilXBTのガイドでも、Claude Codeは「コーディングアシスタント」ではなく「最小限の監督でプロジェクト全体を構築・テスト・デプロイできる自律エージェント」と位置づけられています。

この差はツールの性能ではなく、周辺の設定で決まります。プロジェクトの前提を毎回伝える仕組み、繰り返し作業を定型化する仕組み、セッションを維持する仕組みがなければ、エージェントOSにはなりません。

前提条件

ローカルでClaude Agent OSの土台を作る場合、以下が必要です。

  • Node.js 18以上（公式クイックスタートでは18+、AgentOSテンプレートではNode 20 LTSを使用）
  • Anthropic APIキー、またはClaude CodeのOAuth認証
  • 作業用プロジェクトディレクトリ

常時稼働のOSS版を使う場合は、macOSならHomebrew、ソースからならuvが推奨されます。VPS版AgentOSはmacOS上のインストールウィザードからLinuxサーバーをプロビジョニングする構成です。

ステップ1：Claude Codeをインストールする

https://code.claude.com/docs/en/agent-sdk/quickstart

ターミナルでClaude Codeをグローバルインストールします。

npm install -g @anthropic-ai/claude-code
claude --version

APIキーはAnthropic Consoleで発行し、環境変数に設定します。

export ANTHROPIC_API_KEY=your_key_here

macOSやLinuxでは~/.zshrcに追記すると再起動後も保持されます。プログラムからエージェントを組む場合は、Pythonならclaude-agent-sdk、TypeScriptなら@anthropic-ai/claude-agent-sdkをプロジェクトに追加します。TypeScript版はClaude Codeバイナリを同梱するため、別途CLIを入れなくても動きます。

ステップ2：CLAUDE.mdでエージェントの記憶を固定する

https://github.com/travis-burmaster/claude-telegram-agent

プロジェクト直下にCLAUDE.mdを置きます。Claude Codeは起動のたびにこのファイルを読み、技術スタック・フォルダ構成・コーディング規約・現在の作業内容を把握した状態でセッションを開始します。

最低限、次の項目を書いておくと効果が大きいです。

  • プロジェクトの目的と対象ユーザー
  • 使用するフレームワーク・データベース・デプロイ先
  • ディレクトリ構成の説明
  • Claude Codeに禁止する操作（.envの読み取り、無確認のgit pushなど）

CyrilXBTのガイドでは、CLAUDE.mdの具体性が成果の差を生むと強調されています。ここが薄いと毎回ゼロから説明が必要になり、エージェントOSとしての利点が消えます。

ステップ3：スキルとルーティンでワークフローを再利用する

.claude/skills/にMarkdown形式のスキルファイルを置くと、「コードレビューして」「この機能を計画して」といった定型指示を名前で呼び出せます。スキルにはトリガー文言、手順、出力形式を書きます。

.claude/routines/には定期実行ワークフローを定義できます。例として、毎朝9時に直近24時間の変更ファイルをレビューしてレポートを保存する、といった運用が可能です。スキルとルーティンを揃えると、単発のチャットから「手順が固定されたエージェント」へ移行できます。

ステップ4：最初のエージェントを実行する

ローカルでClaude Codeを起動する

プロジェクトフォルダでclaudeを実行し、最初のタスクを自然文で指示します。

cd your-project-folder
claude

例：「src/components配下を読み、重複ロジックとリファクタ候補をリストアップして」と依頼します。セッションが長くなるとコンテキストが圧迫されるため、/compactで会話を要約し、/clearで履歴をリセットする操作を覚えておきます。

Agent SDKで自律ループを動かす

Pythonの最小例は次のとおりです。query関数がエージェントループを起動し、Read・Edit・Globツールを自動承認します。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="utils.pyのクラッシュ要因を調査し修正してください",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        print(message)

asyncio.run(main())

uv run agent.pyまたはpython agent.pyで実行します。エージェントはファイルを読み、問題を分析し、編集まで自律的に行います。

ステップ5：常時稼働のClaude Agent OSを立ち上げる

ローカル対話だけでは「寝ている間も動くエージェント」にはなりません。常時稼働が必要なら、OSSのClaude Agent OSを使います。

macOS（Homebrew）

brew tap travis-burmaster/claude-telegram-agent
brew install --HEAD claude-agent-os
claude-agent setup
brew services start claude-agent-os
open http://127.0.0.1:8420

claude-agent setupでデータディレクトリとWeb UIのパスワードを設定します。デフォルトのWebダッシュボードはhttp://127.0.0.1:8420で、チャット・タスク・メモリ・Cron・ログをブラウザから操作できます。

ソースからインストール

git clone https://github.com/travis-burmaster/claude-telegram-agent
cd claude-telegram-agent
uv sync
uv run claude-agent setup
uv run claude-agent server --with-proxy

--with-proxyは同梱のOAuthプロキシを127.0.0.1:8319で自動起動します。CLI認証が不安定な環境で有効です。

設定ファイルの要点

設定は~/.claude-agent-os/config.yamlに集約されます。主要項目は次のとおりです。

  • agent.model：使用モデル（デフォルトはclaude-sonnet-4-6）
  • agent.max_concurrent_agents：同時実行するサブエージェント数（デフォルト3）
  • web.port：Web UIのポート（デフォルト8420）
  • telegram.bot_tokenとtelegram.allowed_users：Telegram連携と許可ユーザーID
  • paths.soul：エージェントの人格・指示を書くsoul.mdへのパス

Telegramを使う場合は@BotFatherでボットを作成し、許可するユーザーIDをallowed_usersに登録します。設定変更後はbrew services restart claude-agent-osで再起動します。

VPSでTelegramエージェントを動かす（AgentOSテンプレート）

https://github.com/try-agent-os/claude-agent-os

サーバー常駐が目的なら、AgentOSテンプレートが別ルートです。macOS上で次を実行すると、GitHubフォーク作成・VPSプロビジョニング・18ステップのインストールまでウィザードが進めます。

curl -fsSL https://raw.githubusercontent.com/try-agent-os/claude-code-template/main/install.sh | bash

インストール後はsystemdでagent-os-operator（Telegram待受）、agent-os-saga（タスク追跡）、agent-os-dispatcher（45分間隔の定期実行）が稼働します。DigitalOceanのs-2vcpu-4gb（月額約24ドル）が最低推奨スペックとされています。

トラブルシューティング

APIキーが見つからない

.envまたはシェル環境にANTHROPIC_API_KEYが設定されているか確認します。Agent SDKのクイックスタートでも、このエラーは環境変数未設定が主因と案内されています。

認証が不安定

claude-agent server --with-proxyでプロキシを併用するか、claude-agent doctorで依存関係と設定を診断します。

会話が迷走する

/clearで履歴をリセットし、CLAUDE.mdの禁止事項と作業範囲を具体化します。複数ファイルを触る前に「変更前に必ず該当ファイルを読む」ルールをCLAUDE.mdに明記すると精度が上がります。

Telegramから応答がない

config.yamlのbot_tokenとallowed_usersを確認し、サービスを再起動します。AgentOSテンプレートではscripts/verify.shが50以上のヘルスチェックを実行します。

ローカル構築と常時稼働OSSの使い分け

目的 おすすめ構成
手元のプロジェクトで自律開発を試す Claude Code + CLAUDE.md + スキル
プログラムからエージェントを組み込む Agent SDK（Python/TypeScript）
Mac上で常時稼働・Web UI・Telegram travis-burmaster/claude-telegram-agent
VPSで24時間Telegramエージェント try-agent-os/claude-agent-os

Claude Agent OSの本質は、Claude Codeに「記憶」「手順」「常駐」の3層を足すことです。20分で押さえるべきポイントは、CLIの導入、CLAUDE.mdの作成、最初の1タスク実行、必要ならOSSで常時稼働化する、の4点に集約できます。