Zenn
Open2

keep4o-jp

VTeacherVTeacher

keep4o セットアップガイド

<context_gathering>
keep4oは、Next.js、Vercel AI SDK、OpenAI、Vercel KVで構築されたオープンソースのAIチャットボットアプリテンプレートです。
このガイドでは、keep4oをローカルで動作させるための完全なセットアップ手順を説明します。
</context_gathering>

前提条件

  • Node.js（バージョン18以上）
  • pnpm（パッケージマネージャー）
  • Git（リポジトリのクローン用）

セットアップ手順

1. システム要件の確認

<verification>
現在のシステム環境を確認してください：
</verification>

# Node.jsのバージョンを確認
node --version

# pnpmを確認（利用できない場合はインストール）
pnpm --version || npm install -g pnpm

# Gitを確認
git --version

2. 依存関係のインストール

# プロジェクトディレクトリに移動
cd /path/to/keep4o

# 依存関係をインストール
pnpm install

3. 環境変数の設定

<persistence>
重要: 以下のすべての環境変数が必要です。次に進む前に、すべてのサービスアカウントを作成し、必要な情報を準備してください。
</persistence>

必要なサービスの設定

事前設定が必要なサービス：

  1. OpenAI API キー（必須）

    • OpenAI Platformで請求アカウントを有効化
    • API KeysからAPIキーを生成
    • 🔑 OPENAI_API_KEYを保存

  2. Google OAuth（必須）

    • Google Cloud ConsoleでOAuthクライアントを作成
    • 承認済みリダイレクトURI: http://localhost:3000/api/auth/callback/google
    • 🔑 GOOGLE_CLIENT_IDとGOOGLE_CLIENT_SECRETを保存

  3. Vercel KVデータベース（必須）

環境変数の設定

上記の情報を準備したら、以下を実行してください：

# .envファイルを作成
cp .env.example .env

# AUTH_SECRETを生成
openssl rand -base64 32

.envファイルに以下のすべてを設定してください：

NEXT_PUBLIC_API=http://localhost:3000
NEXTAUTH_URL=http://localhost:3000

# OpenAI API キー（必須）
OPENAI_API_KEY=sk-proj-...

# 生成されたシークレット（必須）
AUTH_SECRET=your_generated_random_key

# Google OAuth（必須）
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# Vercel KVデータベース（必須）
KV_URL=redis://your_kv_url
KV_REST_API_URL=https://your_kv_rest_api_url
KV_REST_API_TOKEN=your_kv_rest_api_token
KV_REST_API_READ_ONLY_TOKEN=your_kv_rest_api_read_only_token

4. 環境変数の確認

すべての環境変数が設定されていることを確認してください：

# .envファイルをチェック（機密情報は表示されません）
grep -E '^[A-Z]' .env | grep -v '=$'

次のステップに進む前に、すべての必要項目に値が設定されていることを確認してください。

5. アプリケーションの起動

<exploration>
開発サーバーを起動し、アプリケーションが正常に動作することを確認してください：
</exploration>

# 開発サーバーを起動
pnpm dev

# 代替コマンド
pnpm run dev

6. 機能の確認

  1. ブラウザでhttp://localhost:3000にアクセス
  2. ログイン機能：
    • GoogleでのOAuthログインが動作することを確認
    • ログイン後にチャットインターフェースが表示されることを確認
  3. チャット機能：
    • メッセージを送信してAIが応答することを確認
    • 会話履歴が保存されることを確認

トラブルシューティング

よくある問題と解決策

ポート3000が使用中の場合：

# 別のポートで起動
pnpm dev -- --port 3001

環境変数が正しく読み込まれない場合：

  • .envファイルがプロジェクトルートにあることを確認
  • 環境変数名のタイプミスをチェック
  • すべての環境変数が空でないことを確認（すべての値が設定されている必要があります）
  • サーバーを再起動

OpenAI APIエラー：

  • OpenAI PlatformでAPIキーが有効であることを確認
  • 請求アカウントが有効化されていることを確認
  • API使用制限を超えていないかチェック
  • APIキーがsk-proj-またはsk-で始まっていることを確認

認証エラー：

  • AUTH_SECRETが適切に設定されていることを確認
  • Google OAuthの設定が正しいことをチェック
  • コールバックURLを確認：http://localhost:3000/api/auth/callback/google
  • Google OAuthアプリが制限されていないことを確認

データベース/KVエラー：

  • 4つのKV環境変数がすべて設定されていることを確認
  • Vercel KVダッシュボードで接続状態をチェック
  • KV URLとトークンが正しいことを確認

追加設定

Vercelデプロイ

# Vercel CLIをインストール（未インストールの場合）
npm i -g vercel

# プロジェクトをVercelにリンク
vercel link

# Vercelから環境変数を取得
vercel env pull

開発ツール

コード品質チェック：

# リントを実行
pnpm run lint

本番ビルドのテスト：

# 本番ビルド
pnpm run build

# 本番サーバーを起動
pnpm run start

完了チェックリスト

セットアップ準備：

  • Node.js（v18以上）がインストール済み
  • pnpmがインストール済み
  • プロジェクトの依存関係がインストール済み

外部サービスの準備：

  • OpenAI請求アカウントが有効化され、APIキーを取得済み
  • 正しいコールバックURLでGoogle OAuthアプリを作成済み
  • Vercel KVデータベースを作成し、認証情報を取得済み

環境変数の設定：

  • .envファイルを作成済み
  • すべての必要な環境変数が設定済み（空の値なし）
  • AUTH_SECRETを生成して設定済み

機能確認：

  • 開発サーバーがエラーなく起動
  • http://localhost:3000にアクセス可能
  • Google OAuthログイン機能が動作
  • チャット機能が動作し、AIが応答
  • 会話履歴がKVデータベースに保存される

セットアップが完了すると、keep4oを使ってAIとチャットを開始できます！

セットアップ後のトラブルシューティング

セットアップ完了後に問題が発生した場合は、以下の特定の箇所を確認してください：

🔐 ログインできない（Google認証が失敗）

  • .env内のGoogle OAuthキーを確認：
    • GOOGLE_CLIENT_IDが正しいことを確認
    • GOOGLE_CLIENT_SECRETが正しいことを確認
    • Google Cloud ConsoleでコールバックURLがhttp://localhost:3000/api/auth/callback/googleに設定されていることを確認
    • Google OAuthアプリが特定のドメインに制限されていないことを確認

💬 チャットが機能しない（AIが応答しない）

  • .env内のOpenAI APIキーを確認：
    • OPENAI_API_KEYが正しく有効であることを確認
    • OpenAIアカウントで請求が有効化されていることを確認
    • 十分なAPIクレジット/クォータがあることを確認
    • APIキーがsk-proj-またはsk-で始まっていることを確認

💾 チャット履歴が保存されない

  • .env内のVercel KV認証情報を確認：
    • 4つのKV環境変数がすべて正しく設定されていることを確認：
      • KV_URL
      • KV_REST_API_URL
      • KV_REST_API_TOKEN
      • KV_REST_API_READ_ONLY_TOKEN
    • Vercel KVデータベースがアクティブでアクセス可能であることを確認

💡 プロ向けのヒント： 環境変数を変更した後は、変更を適用するためにpnpm devで開発サーバーを再起動してください。

VTeacherVTeacher

keep4o 開発者向け実践コーディングガイド

<context_gathering>
keep4oは、Next.js、Vercel AI SDK、OpenAI、Vercel KVで構築されたオープンソースのAIチャットボットアプリテンプレートです。
この包括的なガイドは、初心者がプロジェクト構造を理解し、新機能を効率的に開発する（実践的なコーディング）ために設計されています。
</context_gathering>

📋 keep4oとは？

keep4oは本番環境対応のAIチャットアプリケーションで、以下の機能を提供します：

  • リアルタイムAI会話: OpenAIのGPT-4oモデルとのチャット
  • ユーザー認証: 安全なGoogle OAuthログインシステム
  • 永続的なチャット履歴: すべての会話が自動的に保存
  • モダンUI: すべてのデバイスに対応したクリーンでレスポンシブなデザイン
  • チャット共有: 他の人と会話を公開共有

🏗️ コア技術スタック

初心者向け解説： これらが作業で使用する主要技術です：

  • Next.js 15: Reactフレームワーク（ルーティング、サーバーサイド機能を担当）
  • OpenAI SDK: ChatGPT類似のAIモデルに接続
  • Vercel AI SDK: AIチャットインターフェースの構築を簡単にする
  • NextAuth.js: ユーザーのログイン/ログアウトを安全に処理
  • Vercel KV: チャットメッセージ保存用データベース（Redisのような）
  • Tailwind CSS: 美しいインターフェース用のスタイリングシステム

🎯 主要な開発領域：変更を加える場所

🎨 app/(chat)/ - チャットUIとインターフェース

📝 初心者にとって重要： ここはチャットインターフェースとユーザーエクスペリエンスを変更する場所です。

ここを編集するとき：

  • メッセージの見た目や動作を変更
  • チャットレイアウトやデザインを修正
  • チャット画面に新しいUI要素を追加
  • サイドバーやナビゲーションをカスタマイズ

主要ファイルの説明：

app/(chat)/page.tsx - 新しいチャットの開始点

// 機能: ユーザーがホームページを訪問したときに新しいチャットを作成
// 主要機能: nanoid()を使用してユニークなチャットIDを生成
// 初心者のヒント: ユーザーがチャットを開始するときに最初に読み込まれるファイル

app/(chat)/layout.tsx - 全体的なチャット画面レイアウト

// 機能: サイドバー、レスポンシブデザイン、全体レイアウトを制御
// 主要機能:
// - サイドバー幅: 大画面で250px、特大画面で300px
// - モバイルレスポンシブ対応を自動処理
// - アニメーションとオーバーフロー動作を制御

app/(chat)/chat/[id]/page.tsx - 個別のチャット会話

// 機能: IDによる既存チャット会話の読み込み
// 主要機能:
// - ユーザーがログインしているかチェック（認証）
// - データベースからメッセージ履歴を読み込み
// - 他のユーザーのチャットへのアクセスを防止
// - ページタイトルを動的に生成

🤖 app/api/ - LLMとAI機能

📝 初心者にとって重要： ここはAI機能を追加し、外部APIと統合し、高度な機能を処理する場所です。

ここを編集するとき：

  • AIエージェント機能を追加
  • RAG（検索拡張生成）を実装
  • ウェブ検索機能を追加
  • AIモデルや動作を変更
  • 外部AIサービスと統合
  • DeepSearchや高度なAI機能を実装

主要ファイル：app/api/chat/route.ts - AI相互作用の中核

🔧 現在のLLM設定：

// 現在のAIモデル: GPT-4o（OpenAIの最も高度なモデル）
model: 'gpt-4o',  // 代替: 'gpt-4o-mini' より高速/安価な応答用
temperature: 0.7,  // 創造性を制御（0.0 = 決定論的、1.0 = 非常に創造的）
stream: true      // リアルタイム応答ストリーミングを有効

💾 メッセージ履歴とコンテキスト管理：

// 動作方法:
// 1. フロントエンドから以前のメッセージをすべて受信
// 2. 完全な会話履歴をOpenAIに送信
// 3. AI応答をリアルタイムでストリーミングバック
// 4. 完全な会話をRedisデータベースに保存

// コンテキストサイズ: 現在無制限（GPT-4oの128kトークン制限に依存）
// ストレージ: ユーザーがチャットを削除するまでメッセージは永続的に保存

🚀 高度な機能への拡張方法：

RAG（検索拡張生成）の追加：

// OpenAI API呼び出しの前に追加:
const relevantDocs = await searchDocuments(userMessage);
const enhancedMessages = [
  { role: 'system', content: `コンテキスト: ${relevantDocs}` },
  ...messages
];

ウェブ検索の追加：

// ユーザーが現在の情報を必要とするときを検出:
if (needsWebSearch(userMessage)) {
  const searchResults = await searchWeb(userMessage);
  // 検索結果を会話に注入
}

AIエージェント機能の追加：

// 関数呼び出しを有効化:
const res = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages,
  tools: [
    {
      type: 'function',
      function: {
        name: 'search_web',
        description: '現在の情報を検索'
      }
    }
  ]
});

💾 app/actions.ts - メッセージ履歴とデータベース操作

📝 初心者にとって重要： このファイルはすべてのチャット履歴、ユーザーデータ、データベース操作を管理します。

ここを編集するとき：

  • チャット履歴の保持期間を調整
  • コンテキストサイズ制限を修正
  • メッセージの保存や取得方法を変更
  • チャット検索機能を追加
  • チャット分類を実装

主要関数の説明：

getChats() - ユーザーの全チャットを取得

// 機能: ログインユーザーの全チャットリストを取得
// 戻り値: チャットタイトル、ID、作成日
// セキュリティ: 現在のユーザーに属するチャットのみ表示

getChat(id) - 特定の会話を取得

// 機能: 1つのチャットの完全なメッセージ履歴を読み込み
// セキュリティ: 読み込み前にユーザーがこのチャットを所有していることを確認
// 使用法: ユーザーがサイドバーでチャットをクリックしたときに呼び出される

removeChat(id) & clearChats() - 会話を削除

// removeChat: 1つの特定の会話を削除
// clearChats: すべてのユーザー会話を削除（一括削除）
// セキュリティ: 両方とも削除前にユーザーの所有権を確認

🎛️ components/ - 共有UIコンポーネント

📝 初心者にとって重要： このディレクトリには、再利用可能なインターフェース要素とコンポーネントがすべて含まれています。

ここを編集するとき：

  • メッセージ、ボタン、フォームの外観を修正
  • 機能用の新しいUIコンポーネントを追加
  • サイドバー、ナビゲーション、認証要素を変更
  • アイコン、ダイアログ、対話要素をカスタマイズ

チャット関連コンポーネント：

components/chat.tsx - メインチャットコンテナ

// 機能: チャットインターフェース全体を管理する中央コンポーネント
// 主要機能: useChatフックを使用、メッセージ状態を処理、API呼び出しを管理
// 初心者のヒント: すべてのチャット機能を調整

components/chat-message.tsx - 個別メッセージ表示

// 機能: 各メッセージを表示（ユーザーとAIメッセージの両方）
// 主要機能:
// - リッチテキスト用のMarkdownレンダリング
// - コードブロックのシンタックスハイライト
// - メッセージのコピー/共有ボタン

components/prompt-form.tsx - メッセージ入力フォーム

// 機能: ユーザーがメッセージを入力するテキスト入力
// 主要機能:
// - 自動リサイズのテキストエリア
// - Enterで送信、Shift+Enterで改行
// - 文字数カウントと検証

認証コンポーネント：

components/login-button.tsx - Google OAuthログイン

// 機能: 「Googleでサインイン」ボタン
// 機能: OAuthフローを処理、読み込み状態表示、エラーハンドリング

components/user-menu.tsx - ユーザープロファイルドロップダウン

// 機能: ユーザー情報とログアウトオプションを表示
// 表示場所: ユーザーがログインしているときの右上角

UI基盤コンポーネント（components/ui/）：

components/ui/button.tsx - 再利用可能ボタン

// 利用可能バリアント: default, outline, ghost, destructive
// サイズ: small, medium, large
// 使用法: 一貫したスタイリングのためにアプリ全体でインポートして使用

components/ui/dialog.tsx - モーダルウィンドウ

// 機能: 確認、フォームなどのポップアップウィンドウを作成
// 使用法: チャット共有、削除確認などで使用

components/ui/icons.tsx - アイコンライブラリ

// 含有: 25以上のSVGアイコン（送信、コピー、共有、削除など）
// 使用法: 名前で特定のアイコンをインポート
// 初心者のヒント: すべてのアイコンは一貫してスタイル設定されている

カスタムフック（lib/hooks/）：

lib/hooks/use-chat.tsx - チャット状態管理

// 機能: チャットメッセージ、API呼び出し、ストリーミングを管理
// 主要機能: リアルタイムメッセージ更新、エラーハンドリング、読み込み状態
// 使用法: メインチャットコンポーネントで使用

lib/hooks/use-sidebar.tsx - サイドバー状態

// 機能: サイドバーの開閉状態を制御
// 永続化: ユーザー設定をlocalStorageに保存
// レスポンシブ: モバイルで自動非表示、デスクトップで開いたまま

🔧 初心者向け開発パターン

1. ファイル組織戦略

  • ルートグループ: (chat)は関連ページをグループ化
  • APIルート: 各エンドポイントは個別のroute.tsファイル
  • コンポーネント: 機能別に組織化（chat、auth、ui）

2. サーバー vs クライアントコンポーネント

  • サーバーコンポーネント: Next.js 15でデフォルト、サーバーで実行
  • クライアントコンポーネント: インタラクティブ要素用に'use client'を使用
  • サーバーアクション: データベース操作用に'use server'を使用

3. 認証フロー

  • すべてのチャットルートが自動的に認証をチェック
  • 未認証ユーザーはログインページにリダイレクト
  • ユーザーデータは分離（他のユーザーのチャットは見えない）

4. データベース操作

  • Vercel KVを使用したRedisベースストレージ
  • パイプラインを使用したアトミック操作
  • 分離のためのユーザー固有データキー

🎯 初心者の一般的なタスクと開始場所

🎨 チャット外観のカスタマイズ

開始場所: components/chat-message.tsx, components/chat-panel.tsx
例:

  • メッセージバブルの色を変更
  • ユーザーアバターを追加
  • 入力フォームレイアウトを修正

🤖 AI機能の追加

開始場所: app/api/chat/route.ts
例:

  • GPT-4oからGPT-4o-miniに変更
  • 特定の動作用のシステムプロンプトを追加
  • シンプルな関数呼び出しを実装

📱 UI改善

開始場所: components/ui/ディレクトリ
例:

  • ボタンとダイアログをカスタマイズ
  • 新しいアイコンを追加
  • レスポンシブ動作を修正

⚙️ 設定変更

開始場所: 環境変数とapp/actions.ts
例:

  • メッセージ履歴制限を調整
  • 認証プロバイダーを変更
  • データベースクリーンアップポリシーを修正

🛡️ セキュリティとベストプラクティス

組み込みセキュリティ機能：

  • ユーザー分離: 各ユーザーは自分のチャットのみにアクセス可能
  • 認証ガード: すべての保護されたルートがログイン状態を確認
  • 入力検証: すべての操作でサーバーサイド検証
  • CSRF保護: NextAuth.jsによる自動保護
  • 環境変数: APIキーは安全に保存

パフォーマンス最適化：

  • エッジランタイム: APIルートが速度のためにVercel Edgeで実行
  • ストリーミング応答: リアルタイムAI応答
  • コンポーネントメモ化: 大きなチャット用の最適化されたレンダリング
  • データベースインデックス: 効率的なチャット取得

🚀 最初の修正を始める

初心者プロジェクトアイデア：

  1. AIの個性を変更

    • app/api/chat/route.tsを編集
    • 特定の動作用のシステムプロンプトを追加

  2. メッセージ外観をカスタマイズ

    • components/chat-message.tsxを編集
    • 色、フォント、レイアウトを変更

  3. シンプルな機能を追加

    • components/prompt-form.tsxにメッセージ単語数
    • components/empty-screen.tsxにカスタムユーザー挨拶

  4. ナビゲーションを修正

    • components/sidebar-*.tsxファイルを編集
    • 新しいメニューアイテムを追加またはチャットを整理

開発ワークフロー：

  1. 特定 - 変更がどのディレクトリに属するかを特定
  2. 見つける - その機能を担当する特定のファイルを見つける
  3. 読む - パターンを理解するために既存のコードを読む
  4. 作成 - 小さな段階的変更を作成
  5. テスト - 次に進む前に各変更をテスト

🎉 おめでとうございます！これでkeep4oのアーキテクチャを理解し、素晴らしいAI機能の構築を始める準備が整いました！

💡 プロのヒント: コードベースに慣れるためにcomponents/ディレクトリでの小さな変更から始め、自信がついたらapp/api/のより複雑な機能に移行してください。