OpenAIのChatKit Starterアプリ(openai-chatkit-starter-app)は、ChatKitのチャットUIを動かすための公式テンプレートです。2025年10月の公開時はNext.jsの1本構成でしたが、2025年12月に作り直され、現在はVite+React+FastAPIの2テンプレートに分かれています。ただしリポジトリは2026年3月27日のコミットから更新が無く、そのまま動かすとUI部品は1.1.1、Agents SDKは0.22.2、モデルは非推奨の gpt-4.1-mini という古い組み合わせで起動します。加えてAgent Builderは2026年11月30日に終了する予定です。この記事では、2026年11月8日にリポジトリを手元で動かし、起動・最新版への更新・型検査とビルド・リクエストの応答までを確かめた手順と、本番に出す前に差し替える箇所を整理します。有効なAPIキーでのモデル応答とブラウザ表示は確認範囲に含みません。
まとめ:ChatKit Starterアプリの要点(2026年11月時点)
- 新しく作るなら自前ホスト版の
chatkit/を使います。Agent Builderを使うmanaged-chatkit/は、2026年11月30日のAgent Builder終了とともに動かなくなる予定です。 - 自前ホスト版は
npm installとnpm run devで、FastAPI(127.0.0.1:8000)とVite(127.0.0.1:3000)が同時に起動します。必要な環境変数はOPENAI_API_KEYだけです。Python 3.11以上と、Node.js 20.19以上の20系か22.12.0以上が要ります。 - 起動したら3か所を最新にそろえます。lockで固定された @openai/chatkit-react 1.1.1、
fastapi<0.116の上限で止まる openai-agents 0.22.2、2027年1月14日に削除されるgpt-4.1-miniの3つです。 - テンプレートは会話をメモリに置き、CORSはすべてのオリジンを許可し、ドメインキーには開発用の値が入っています。本番前に、この3点とユーザーIDの扱いを差し替えます。
- ChatKit本体の提供は続きます。Agent Builderのワークフローは「Code」から Agents SDK のコードとして書き出し、自前サーバーの中で動かします。
ChatKitとStarterアプリの関係
ChatKitは、エージェントと対話するチャット画面をWebページに埋め込むための、OpenAIのUI部品です。メッセージのストリーミング表示、スレッド管理、ファイル添付、ツール実行中の表示、ウィジェット(カードやフォーム)の描画を受け持ちます。開発者はエージェントの処理と認証に集中できます。
部品ごとのパッケージと最新版
| 部品 | パッケージ | 最新版 | Starterで入る版 |
|---|---|---|---|
| Web部品の型定義 | @openai/chatkit(npm) | 1.9.0(2026-07-31) | 1.0.0 |
| Reactバインディング | @openai/chatkit-react(npm) | 1.6.1(2026-07-31) | 1.1.1 |
| サーバーSDK | openai-chatkit(PyPI) | 1.6.5(2026-05-19) | 1.6.5 |
| Agents SDK | openai-agents(PyPI) | 0.24.0(2026-10-15) | 0.22.2 |
「Starterで入る版」は、2026年11月8日に手元でlockと pyproject.toml のまま導入した結果です。UI本体は npm には含まれず、CDNの https://cdn.platform.openai.com/deployments/chatkit/chatkit.js から読み込みます。npmのパッケージは型定義とReactの包みで、画面の機能そのものはCDN側が提供します。PyPIのopenai-chatkitは openai-agents>=0.3.2 に依存し、Agents SDKの出力をChatKitのイベントへ変換する補助関数を同梱しています。公式ガイドはAgents SDK以外のエージェントサービスにもつなげると説明しており、Agents SDKを使うのはStarterの構成上の選択です。
コードを書かずに試せるChatKit playground
見た目や操作感を確かめるだけなら、Starterを動かす必要はありません。公式ドキュメントは、触りながら学べる対話型デモとしてChatKit playgroundとchatkit.worldを、ウィジェットの部品を一覧できる場としてWidget builderを案内しています。
chatkitとmanaged-chatkitの違い
リポジトリ直下には2つのディレクトリがあり、エージェントがどこで動くかが違います。
| 項目 | chatkit(自前ホスト) | managed-chatkit(Agent Builder) |
|---|---|---|
| エージェントの実行場所 | 自分のFastAPI | OpenAIがホスト |
| バックエンドの役割 | /chatkit で全リクエストを処理 | /api/create-session でセッション発行のみ |
| 必須の環境変数 | OPENAI_API_KEY | OPENAI_API_KEY+ワークフローID |
| 会話の保存先 | 自前のStore(初期はメモリ) | OpenAI側 |
| 2026-11-30以降 | 継続して使える | Agent Builder終了で停止予定 |
2026年11月以降に新しく始めるなら、managed-chatkit を選ぶ理由はありません。OpenAIのChatKitガイドも、ホスト型のワークフローを使う手順を「すでにAgent Builderのワークフローを持っている場合だけ」に絞り、新規開発には自前サーバーでの統合(advanced integration)を勧めています。Agent Builder自体は2026年6月3日に非推奨が告知され、11月30日に終了する予定です(OpenAIのDeprecationsページ)。Agent Builderのノードや移行先の選び方はOpenAI Agent Builderとは?11月30日終了前の移行手順と移行先3つの選び方で扱っています。
自前ホスト版(chatkit)の起動手順
必要な環境:PythonとNode.jsの対応バージョン
バックエンドの pyproject.toml は requires-python = ">=3.11" です。起動スクリプト backend/scripts/run.sh は、PATH上の python コマンドで仮想環境を作ります。macOS付属のPython 3.9.6で作った仮想環境では、pip install -e . が「editable mode currently requires a setuptools-based build」で止まりました。python が3.11以上を指すようにしてから起動します。
フロントエンドの package.json にある "engines": { "node": ">=18.18" } は古い記述です。依存の vite ^7.1.9 は node ^20.19.0 || >=22.12.0 を要求するため、Node.js 18、21系、22.0〜22.11はサポート対象外です。
起動コマンドと.env.localの置き場所
git clone https://github.com/openai/openai-chatkit-starter-app.git
cd openai-chatkit-starter-app
git checkout 9cf32e6 # この記事で検証したコミット(2026-03-27)。最新を使うなら省く
cd chatkit
# chatkit/ 直下に .env.local を作る(run.sh と vite の両方がここを読む)
echo 'OPENAI_API_KEY=sk-proj-...' > .env.local
npm install # ルートの concurrently だけが入る
npm run dev # backend:8000 と frontend:3000 を同時に起動
npm run dev は、backend/.venv が無ければ作り、毎回 pip install -e . を実行してから uvicorn を起動します。フロントエンドも毎回 npm --prefix frontend install を実行してからViteを起動します。ブラウザで http://127.0.0.1:3000 を開くと、Viteが /chatkit へのリクエストを8000番ポートへ中継します。
run.sh は backend/../.env.local を読み、vite.config.ts も envDir を1つ上の階層に向けているため、chatkit/ 直下の1ファイルを両方が読みます。ただし run.sh は、シェルに OPENAI_API_KEY がすでにある場合はファイルを読みません。別のプロジェクトのキーがシェルに残っていると、そちらが使われます。
リクエストの流れ:/chatkitの1エンドポイント
自前ホスト版のバックエンドは、POST /chatkit の1本だけを公開します。ChatKitのWeb部品が送るJSONの type(threads.create、threads.list、threads.add_user_message など)を ChatKitServer.process() が振り分け、SSE(text/event-stream)かJSONで返します。
curl -s -X POST http://127.0.0.1:8000/chatkit \
-H 'Content-Type: application/json' \
-d '{"type":"threads.list","params":{"limit":10}}'
# => {"data":[],"has_more":false}
モデルへの問い合わせは backend/app/server.py の respond() で行います。直近30件の履歴を simple_to_agent_input() でAgents SDKの入力に変え、Runner.run_streamed() に渡し、stream_agent_response() でChatKitのイベントへ変換して返します。指示文(instructions)とモデルは、このファイル冒頭の assistant_agent で書き換えます。Agents SDKでツールやハンドオフを足す書き方は、AIエージェントフレームワークとは?主要8種の比較・動作コード・選定基準【2026年9月版】に動くコードを載せています。
Starterの依存とモデルを最新にそろえる3か所
Starterのリポジトリは2026年3月27日のコミットが最後で、その後に出た版を取り込んでいません。動かしてすぐ、次の3か所を直します。
フロントエンド:chatkit-react 1.1.1から1.6.1への更新
frontend/package-lock.json は @openai/chatkit-react 1.1.1 と @openai/chatkit 1.0.0 を固定しています。CDNの画面本体は常に新しいので動きはしますが、型定義が古いため、1.2.0以降に足されたオプションをTypeScriptで書くと型検査で落ちます。手元で1.9.0の commands を足したところ、「’commands’ does not exist in type ‘UseChatKitOptions’」(TS2353)で止まりました。
cd frontend
npm install @openai/[email protected] # 依存の @openai/chatkit は1.9.0になる
npx tsc --noEmit # 型検査が通ることを確認
cd ..
更新後は型検査が通り、vite build も成功しました。package.json の指定は ^1.6.1 に書き換わり、lockも更新されるので、そのままコミットします。1.2.0〜1.9.0で増えた主なオプションは、音声入力(composer.dictation)、入力欄のタグ検索ボタン(entities.showComposerMenu)、自動スクロール(thread.autoScroll)、コマンドメニュー(commands)です(chatkit-jsの変更履歴)。
バックエンド:fastapiの上限解除とopenai-agents 0.24.0への更新
backend/pyproject.toml は "fastapi>=0.114,<0.116" と上限を付けています。fastapi 0.115系は starlette 0.47未満を要求する一方、openai-agents は0.22.3(2026年9月17日)から starlette>=1.3.1 を要求します。このためpipは両立する最後の版である0.22.2を選び、最新の0.24.0は入りません。エラーは出ないので、気づかないまま古い版で開発を続けることになります。
# backend/pyproject.toml の fastapi の行を書き換える
# "fastapi>=0.114,<0.116", → "fastapi>=0.135",
rm -rf backend/.venv # 既存のvenvは pip install -e . で上がらないため作り直す
npm run dev
run.sh の pip install -e . は、すでに条件を満たしている依存を上げません。venvを消して作り直すと、fastapi 0.162.2、starlette 1.10.0、openai-agents 0.24.0、openai-chatkit 1.6.5 の組み合わせになり、pip check も問題なしでした。この状態で起動し、threads.list と threads.create が1巡目と同じ形で応答することを確かめています。
モデル:2027年1月14日に削除されるgpt-4.1-miniの差し替え
server.py は MODEL = "gpt-4.1-mini" に固定されています。OpenAIは2026年10月14日にGPT-4系の一部モデルの非推奨を告知し、gpt-4.1-mini-2025-04-14(gpt-4.1-mini の既定スナップショット)を2027年1月14日にAPIから削除すると発表しました。推奨の移行先は gpt-6-luna です(Deprecationsページ)。料金は100万トークンあたり入力0.10ドル・出力0.50ドルで、gpt-4.1-mini の入力0.40ドル・出力1.60ドルより安く設定されています(GPT-6 Lunaのモデルページ)。
# backend/app/server.py
MODEL = "gpt-6-luna"
書き換えたサーバーは起動し、リクエストも受け付けました。応答の質と速度は有効なキーで確かめていないため、本番に出す前に代表的な質問で旧モデルと並べて比べてください。
Agent Builder版(managed-chatkit)の起動と環境変数の食い違い
managed-chatkit のバックエンドは、ワークフローIDとAPIキーを使って POST https://api.openai.com/v1/chatkit/sessions(ヘッダー OpenAI-Beta: chatkit_beta=v1)を呼び、返ってきた client_secret をブラウザへ渡す中継役です。ワークフローIDは、Agent Builderでワークフローを公開したときに発行される wf_ で始まる文字列で、APIキーと同じプロジェクトのものが要ります。
注意すべきなのは環境変数の名前です。managed-chatkit/.env.example には NEXT_PUBLIC_CHATKIT_WORKFLOW_ID=wf_... と書かれていますが、フロントエンドの chatkitSession.ts が読むのは VITE_CHATKIT_WORKFLOW_ID です。.env.example をそのままコピーすると、画面に「Set VITE_CHATKIT_WORKFLOW_ID in your .env file.」と出て止まります。2025年12月8日のコミット(#98)でNext.js版の .env.example を中身を変えずに移したためで、READMEのとおり VITE_CHATKIT_WORKFLOW_ID に直します。
このテンプレートのユーザーIDは、Cookie(chatkit_session_id、有効期限30日)に入れたランダムなUUIDです。公式ガイドは、セッション作成時の user に認証済みのエンドユーザーごとに一意なIDを渡すよう求めています。ログインのあるサービスに組み込むなら、自社の認証基盤のユーザーIDに置き換えます。
起動時につまずくエラーと原因
自前ホスト版に無効なAPIキーを入れて threads.create を送ると、thread.created、ユーザーのメッセージ(thread.item.done)、stream_options が返ったあと、{"type":"error","code":"stream.error","allow_retry":true} だけが返りました。401(Incorrect API key provided)の詳細はuvicornのログにしか出ず、失敗した会話もスレッドとして残ります。
- 画面に汎用のエラーしか出ない:APIキーの誤り、削除済みのモデル名、レート制限のどれもブラウザでは同じ
stream.errorに見えます。原因はバックエンドのターミナルのトレースバックで確かめます。 - 「Set OPENAI_API_KEY in your environment or in .env.local」で止まる:
.env.localをbackend/やfrontend/に置いた場合です。chatkit/直下へ移します。 - 8000番か3000番のポートが使用中:
run.shはuvicornを8000番に固定しており、使用中なら起動に失敗します。Viteは3000番を指定していますがstrictPortが無いため、使用中なら次の空き番号で起動します。バックエンドのポートを変えたら、Viteの中継先もCHATKIT_API_BASEで合わせます。 - 再起動すると会話が消える:初期のStoreはPythonの辞書です。uvicornの
--reloadでコードを保存するたびに再起動するため、開発中も会話は消えます。
本番前に差し替える4か所
Starterは「最小構成で動く見本」で、そのまま公開すると危ない設定が入っています。
MemoryStoreから永続化Storeへの置き換え
backend/app/memory_store.py は chatkit.store.Store をメモリ上の辞書で実装した見本で、コメントにも本番では永続化データベースで実装するよう書かれています。添付ファイル用の save_attachment などは NotImplementedError のままで、フロントエンド側も attachments: { enabled: false } です。公式ガイドは、ライブラリの更新でスキーマが変わってもマイグレーションが要らないよう、モデルをJSONのまま保存する方法を勧めています。添付を有効にするなら FileStore の実装も必要です。
全オリジンを許可するCORS設定
main.py は allow_origins=["*"] と allow_credentials=True を同時に指定しています。手元で Origin: https://evil.example を付けてプリフライトを送ると、access-control-allow-origin: https://evil.example と access-control-allow-credentials: true がそのまま返りました。認証Cookieを使う構成で公開すると、他のサイトからAPIを呼べてしまいます。自社のドメインだけを並べたリストに置き換えます。
ドメインキーとドメイン許可リスト
フロントエンドの config.ts は、VITE_CHATKIT_API_DOMAIN_KEY が無いとき domain_pk_localhost_dev を使います。これはローカル開発用の値です。本番では、OpenAIダッシュボードで公開ドメイン用のドメインキーを登録し、発行されたキーを設定します。.env.example には domain_pk_local_dev と別の文字列が書かれているので、開発中は変数を未設定のままにしておきます。
ユーザー認証とStoreのアクセス制御
自前ホスト版は、server.process(body, context) の context にリクエストを入れるだけで、利用者を認証していません。ログイン中のユーザーIDを context に入れ、Storeの読み書きをユーザー単位に絞ります。load_threads がユーザーを区別せずに全スレッドを返す今の実装のままだと、他の利用者の会話一覧が見えてしまいます。社内向けのチャットボットを認証基盤や既存の業務システムとつなぐ段階で設計に迷う場合は、AIチャットボット開発の支援も用意しています。
見た目と入力欄のカスタマイズ
テーマとスタート画面の候補プロンプト
見た目は、Reactなら useChatKit({...})、素のJavaScriptなら chatkit.setOptions({...}) に渡すオプションで変えます。自前ホスト版では frontend/src/components/ChatKitPanel.tsx の useChatKit に足します。
const chatkit = useChatKit({
api: { url: CHATKIT_API_URL, domainKey: CHATKIT_API_DOMAIN_KEY },
theme: {
colorScheme: "dark",
color: { accent: { primary: "#2D8CFF", level: 2 } },
radius: "round",
density: "compact",
},
composer: { placeholder: "社内規程について質問できます" },
startScreen: {
greeting: "何を調べますか?",
prompts: [
{ label: "経費精算の締め日", prompt: "経費精算の締め日はいつですか?", icon: "search" },
],
},
});
候補プロンプトの表示名は label で指定します。OpenAIのテーマガイドの例は2026年11月時点でも name と書いていますが、@openai/chatkit の型定義(1.0.0と1.9.0)は label で、name のままだと型検査でエラーになります。
「/」で開くコマンドメニュー(1.9.0)
1.9.0で追加された commands を有効にすると、入力欄で「/」を打ったときにコマンドの一覧が出ます。検索用の関数が入力に合うコマンドを返し、onSelect が選ばれたコマンドを処理します。onSelect は、タグ(entity)を入力欄に差し込む、別のメニューを開く、何も返さずに画面外の処理だけ行う、のいずれかを選べます。前の節の更新(chatkit-react 1.6.1)を済ませてから書きます。
const COMMANDS = [
{ id: "summarize", label: "要約する", description: "直前の回答を3行にまとめる", icon: "write" as const },
{ id: "policy", label: "規程を探す", description: "社内規程から検索する", icon: "search" as const },
];
const chatkit = useChatKit({
api: { url: CHATKIT_API_URL, domainKey: CHATKIT_API_DOMAIN_KEY },
commands: {
enabled: true,
onSearch: async (query) =>
COMMANDS.filter((c) => c.label.includes(query) || c.id.startsWith(query)),
onSelect: async (command) => {
if (command.id === "summarize") {
await chatkit.setComposerValue({ text: "直前の回答を3行で要約してください" });
} else if (command.id === "policy") {
await chatkit.setComposerValue({ text: "社内規程から次の内容を探してください:" });
}
},
},
});
どちらのコマンドも、選ぶと質問文が入力欄に入り、利用者が続きを書いて送信します。このコードは型検査と vite build までを確かめたもので、画面での表示はOpenAIの公式サンプル(openai-chatkit-advanced-samples の news-guide、2026年8月1日追加)の実装を参考にしてください。サンプルは「/」から入れ子のメニューを開き、選んだ期間の質問文と使うツールを setComposerValue で入力欄に入れる作りです。
ヘッダー・タグ候補・添付・ウィジェット
ヘッダーには header.customButtonLeft と header.customButtonRight でボタンを足せます。entities にタグ候補を返す検索関数を実装すれば、入力欄で「@」を打ったときに社内の人や文書を候補として出せます。ファイル添付は初期状態で無効で、自前のバックエンドを持たない構成では uploadStrategy: { type: "hosted" } を使います。チャット内のカードやフォームは、サーバー側で stream_widget を使って返します。部品の組み方はWidget builderで確かめるのが早いです。
Agent Builder版から自前ホスト版への移行手順
すでに managed-chatkit で運用している場合、11月30日を過ぎるとワークフローIDでのセッション作成ができなくなる予定です。終了日より前に、エージェントの処理を自前のサーバーへ移します。OpenAIの移行ガイドに沿った書き出し手順と、本記事のStarter構成に合わせた組み込み手順は次の通りです。
- Agent Builderでワークフローを開き、上部の「Code」を選ぶ。
- コードのダイアログで「Agents SDK」を選び、PythonかTypeScriptの書き出しをすべてコピーする。
- Python版を、自前ホスト版の
server.pyのassistant_agentとrespond()に組み込み、代表的な入力で元のワークフローと応答を比べる。書き出しにgpt-4.1-miniなどの非推奨モデルが入っていれば、ここで差し替える。 - フロントエンドの
apiをgetClientSecretから{ url, domainKey }に変え、/api/create-sessionを廃止する。
移行ガイドは、書き出しが「ワークフローのグラフを変換するものではなく、すべての挙動がそのまま移る保証もない」と明記しています。分岐の多いワークフローほど、ノード間の制御をコードで書き直す量が増えます。チャット画面が要らず、社内のチーム利用が目的なら、ChatGPTのBusiness・Enterprise・Eduでワークスペースエージェントへ移す道もあります。AgentKitとして同時に発表された製品のその後はOpenAI DevDay 2026の発表まとめ|Dots・GPT-6.1 Solと歴代DevDayの発表のその後にまとめています。
よくある質問
ChatKitは無料で使えますか?
ChatKitのライブラリ(npmとPyPI)は無料で、StarterアプリのライセンスはMITライセンスです。OpenAIに払う費用は、エージェントが呼び出すモデルのトークン料金、Web検索などのツール料金、hosted方式で添付ファイルを置く場合の保存料です。保存料はOpenAIの料金ページで、アカウントごとに月1GBまで無料、超えた分は1GBあたり1日0.10ドルです。自前ホスト版では、これとは別にサーバーとデータベースの運用費がかかります。
ChatKit playgroundとは何ですか?
OpenAIが用意している、ChatKitをブラウザ上で触れる対話型デモです(chatkit.studio/playground)。気に入った見た目は、テーマ・スタート画面・入力欄のオプション(theme、startScreen、composer)として useChatKit に書けば、自分のアプリで再現できます。
iOSアプリでChatKitは使えますか?
2026年11月時点で、OpenAIがGitHubで公開しているChatKitのリポジトリは、chatkit-js、chatkit-python、openai-chatkit-starter-app、openai-chatkit-advanced-samplesの4つで、ネイティブのiOS向けSDKはありません。iOSアプリから使うならWebViewで埋め込みます。iOS向けChatKitの古い記事の多くは、2020年4月23日に終了したPusher社の別製品「Chatkit」を扱っています。
Next.jsでChatKitを使えますか?
使えます。ChatKitの本体はフレームワークに依存しないWeb Componentで、React向けの @openai/chatkit-react があるため、Next.jsでも組み込めます。Starterも公開当初はNext.jsのApp Routerで作られていました。ただし現在のStarterはVite構成のため、Next.jsで書かれた旧版の手順(app/api/create-session/route.ts や NEXT_PUBLIC_ で始まる変数)は、現行リポジトリのファイル構成と一致しません。
Agent Builderが終了したらChatKitも使えなくなりますか?
ChatKit自体は使い続けられます。OpenAIのChatKitガイドとDeprecationsページは、どちらも「ChatKit is still available」「ChatKit remains available」と明記しています。止まるのは、Agent BuilderのワークフローIDを渡してセッションを作る使い方(managed-chatkit)です。自前サーバーでエージェントを動かす構成に移せば、画面側のコードはほぼそのまま使えます。