方法1：Docker Compose（推奨）

version: '3.8'
services:
  neko-main:
    image: docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest
    container_name: neko
    restart: unless-stopped
    ports:
      - "48911:80"   # HTTPポート
      - "48912:443"  # HTTPSポート
    volumes:
      - ./N.E.K.O:/root/Documents/N.E.K.O
      - ./logs:/app/logs
      - ./ssl:/root/ssl
    networks:
      - neko-network
networks:
  neko-network:
    driver: bridge

docker-compose up -d

方法2：Docker Run

NEKO_BASE_PATH="/home/neko/neko-data" && \
docker network create --driver bridge neko-network 2>/dev/null || true
docker run -d \
  --name neko \
  --restart unless-stopped \
  -p 48911:80 \
  -p 48912:443 \
  -v "${NEKO_BASE_PATH}/N.E.K.O:/root/Documents/N.E.K.O" \
  -v "${NEKO_BASE_PATH}/logs:/app/logs" \
  -v "${NEKO_BASE_PATH}/ssl:/root/ssl" \
  --network neko-network \
  docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest

カレントディレクトリ/
├── N.E.K.O/      # 設定ファイルとデータ
├── logs/         # アプリケーションログ
├── ssl/          # SSL証明書
└── docker-compose.yml

🔐 SSL証明書設定

mkdir -p ./ssl
cp your-cert.crt ./ssl/N.E.K.O.crt
cp your-cert.key ./ssl/N.E.K.O.key

docker-compose down
cp your-cert.crt ./ssl/N.E.K.O.crt
cp your-cert.key ./ssl/N.E.K.O.key
docker-compose up -d

docker exec neko openssl x509 -in /root/ssl/N.E.K.O.crt -noout -text

⚙️ 環境変数設定

environment:
  # APIキー
  - NEKO_CORE_API_KEY=${NEKO_CORE_API_KEY}
  - NEKO_ASSIST_API_KEY_QWEN=${NEKO_ASSIST_API_KEY_QWEN}
  - NEKO_ASSIST_API_KEY_OPENAI=${NEKO_ASSIST_API_KEY_OPENAI}
  - NEKO_ASSIST_API_KEY_GLM=${NEKO_ASSIST_API_KEY_GLM}
  - NEKO_ASSIST_API_KEY_STEP=${NEKO_ASSIST_API_KEY_STEP}
  - NEKO_ASSIST_API_KEY_SILICON=${NEKO_ASSIST_API_KEY_SILICON}
  - NEKO_MCP_TOKEN=${NEKO_MCP_TOKEN}

  # APIプロバイダー
  - NEKO_CORE_API=${NEKO_CORE_API:-qwen}
  - NEKO_ASSIST_API=${NEKO_ASSIST_API:-qwen}

  # モデル
  - NEKO_SUMMARY_MODEL=${NEKO_SUMMARY_MODEL:-qwen-plus}
  - NEKO_CORRECTION_MODEL=${NEKO_CORRECTION_MODEL:-qwen-max}
  - NEKO_EMOTION_MODEL=${NEKO_EMOTION_MODEL:-qwen-turbo}
  - NEKO_VISION_MODEL=${NEKO_VISION_MODEL:-qwen3-vl-plus-2025-09-23}

  # SSL
  - SSL_DOMAIN=${SSL_DOMAIN:-project-neko.online}
  - SSL_DAYS=${SSL_DAYS:-365000}
  - DISABLE_SSL=${DISABLE_SSL:-0}
  - AUTO_REGENERATE_CERT=${AUTO_REGENERATE_CERT:-1}
  - NGINX_AUTO_RELOAD=${NGINX_AUTO_RELOAD:-1}

cat > .env << EOF
NEKO_CORE_API_KEY=your_core_api_key_here
NEKO_ASSIST_API_KEY_QWEN=your_qwen_api_key
NEKO_MCP_TOKEN=your_mcp_token
SSL_DOMAIN=your-domain.com
EOF

docker-compose --env-file .env up -d

🔧 トラブルシューティング

ss -tulpn | grep ':4891[12]'
# 解決策：docker-compose.ymlのポートマッピングを変更

mkdir -p N.E.K.O logs ssl
chmod 755 N.E.K.O logs ssl

docker-compose logs --tail=100
docker logs neko --tail=100

rm -f ssl/N.E.K.O.crt ssl/N.E.K.O.key
docker-compose up -d

curl -v http://localhost:48911/health
curl -v -k https://localhost:48912/health

docker ps | grep neko
docker logs neko
docker exec -it neko bash

docker system prune -f
docker-compose down && docker volume prune -f

# docker-compose.ymlで代替イメージソースを試す：
# image: ghcr.io/project-n-e-k-o/n.e.k.o:latest

📊 システム監視

curl http://localhost:48911/health
curl -k https://localhost:48912/health

docker stats neko
docker top neko
docker inspect neko

docker-compose logs -f
docker-compose logs --tail=100
docker-compose logs | grep -i error

tar -czf neko-backup-$(date +%Y%m%d).tar.gz \
  N.E.K.O/ \
  ssl/ \
  docker-compose.yml

docker-compose pull
docker-compose up -d

🌐 アクセスURL

コンテナ起動後：

• HTTP: http://あなたのサーバーIP:48911
• HTTPS: https://あなたのサーバーIP:48912

⏱️ クイックリファレンス

完全な開発者ドキュメントは project-neko.online をご覧ください

要件：Python 3.11（他のバージョンはサポートされていません）、uv パッケージマネージャー、Node.js（>=20.19）

# 1. プロジェクトをクローン
git clone https://github.com/Project-N-E-K-O/N.E.K.O.git
cd N.E.K.O

# 2. Python依存関係をインストール
uv sync

# 3. フロントエンドプロジェクトをビルド（Node.js >= 20.19 が必要。初回実行時またはフロントエンドコード変更後に必要）
#    推奨：一括ビルドスクリプトを使用（公式にサポートされているビルド手順です）
#      Windows：      build_frontend.bat
#      Linux/macOS：  ./build_frontend.sh
#    手動でビルドする場合（スクリプトと同じコマンドを使用してください）：
# cd frontend/react-neko-chat && npm install && npm run build && cd ../..
# cd frontend/plugin-manager && npm install && npm run build-only && cd ../..

# 4. サービスを起動（最低限 main_server と memory_server が必要）
uv run python memory_server.py
uv run python main_server.py
# オプション：Agentサービスを起動
uv run python agent_server.py

# 5. http://localhost:48911 にアクセスしてAPI Keyを設定し、使用開始

開発者はQQグループ 995414391 への参加をお勧めします。

API Keyの設定

追加機能のためにサードパーティAIサービスを設定できます：

• コアAPI（リアルタイム音声会話）：Realtime APIに対応している必要があります。推奨：Alibaba Cloud。
• アシストAPI（記憶/感情/視覚等）：標準ChatCompletionインターフェースに対応。14以上のプロバイダーが利用可能。

http://localhost:48911/api_keyにアクセスして、Web画面から直接設定できます。

Alibaba Cloud APIの取得：Alibaba CloudのBailian Platform公式サイトでアカウント登録します。新規ユーザーは実名認証後に大量の無料クレジットを取得できます。登録完了後、コンソールにアクセスしてAPI Keyを取得してください。

キャラクター設定の変更

• ウェブ版でhttp://localhost:48911/character_card_managerにアクセスするとキャラクター編集ページに入れます。初期の伴侶のプリセット名は小天（XiaoTian）です。名前を直接変更し、基本設定を一つずつ追加または変更することをお勧めします。

• 上級設定にはLive2D/VRM/MMDモデル設定と音声設定が含まれます。Avatarモデルを変更したい場合は、まずモデルディレクトリを本プロジェクトのstaticフォルダにコピーしてください。上級設定からモデル管理画面に入り、モデルを切り替え、ドラッグとマウスホイールでモデルの位置とサイズを調整できます。キャラクター音声を変更したい場合は、約5秒の連続したクリーンな音声録音を準備してください。上級設定から音声クローンページに入り、録音をアップロードするとカスタム音声の設定が完了します。

• キャラクターカードのエクスポートに対応——「設定のみ」または「完全キャラクターカード」形式で共有やバックアップが可能です。

• 上級設定にはさらにsystem_promptがあり、システム命令を完全にカスタマイズできますが、変更は推奨されません。

APIプロバイダーの変更

• http://localhost:48911/api_keyにアクセスすると、コアAPIとアシストAPIのサービスプロバイダーを切り替えられます。

記憶整理

• http://localhost:48911/memory_browserにアクセスすると、最近の記憶と要約を閲覧および校正でき、モデルの繰り返しや認知エラーなどの問題をある程度緩和できます。

プロジェクトアーキテクチャ

N.E.K.O/
├── 📁 .agent/                   # 🤖 AIコーディングアシスタントのルールとスキル（Google Antigravity 規約）
├── 📁 brain/                    # 🧠 エージェントモジュール
│   ├── computer_use.py          # PC操作
│   ├── browser_use_adapter.py   # ブラウザ自動化
│   ├── openclaw_adapter.py      # OpenClawクラウド接続
│   ├── openfang_adapter.py      # OpenFangヘッドレス実行バックエンド
│   ├── task_executor.py         # タスク実行エンジン
│   └── 📁 cua/                  # Computer Use Agentサブシステム
├── 📁 config/                   # ⚙️ 設定管理モジュール
│   ├── api_providers.json       # APIプロバイダー設定
│   └── 📁 prompts/              # キャラクター、システム、機能プロンプト
│       ├── prompts_chara.py     # キャラクタープロンプト
│       └── prompts_sys.py       # システムプロンプト
├── 📁 main_logic/               # 🔧 コアモジュール
│   ├── core.py                  # コア対話モジュール
│   ├── cross_server.py          # クロスサーバー通信
│   ├── omni_realtime_client.py  # リアルタイムAPIクライアント
│   ├── omni_offline_client.py   # テキストAPIクライアント（ChatCompletion）
│   └── tts_client.py            # 🔊 TTSエンジンアダプター
├── 📁 main_routers/             # 🌐 APIルーター（14ルート）
├── 📁 memory/                   # 🧠 五次元メモリシステム（一部例）
│   ├── facts/                   # 事実記憶
│   ├── reflection/              # 反省記憶
│   └── persona/                 # 人格記憶
├── 📁 frontend/                 # 🖥️ モダンフロントエンドプロジェクト
│   ├── react-neko-chat/         # React チャットウィンドウコンポーネント
│   └── plugin-manager/          # Vue プラグイン管理ダッシュボード
├── 📁 plugin/                   # 🔌 プラグインシステム
│   ├── sdk/                     # プラグインSDK
│   └── server/                  # プラグインサーバー
├── 📁 static/                   # 🌐 フロントエンド静的リソース（ビルド成果物を含む）
├── 📁 templates/                # 📄 フロントエンドHTMLテンプレート（14ページ）
├── 📁 utils/                    # 🛠️ ユーティリティモジュール
├── main_server.py               # 🌐 メインサーバー
├── agent_server.py              # 🤖 AIエージェントサーバー
└── memory_server.py             # 🧠 記憶サーバー

AI支援開発：.agent/ ディレクトリは Google Antigravity オープン規約に従い、プロジェクトの開発ルールとスキルセットを格納しています。Antigravity のみ自動読み込み、他のAIツール（Claude Code 含む）は手動インポートが必要です。適応ガイドを参照してください。

データフロー

完全な開発者ドキュメントは project-neko.online をご覧ください

ロードマップ

v0.7: ✅ Agent関連機能の改善。完了。

v0.8：記憶関連機能の改善、OpenClaw類似機能の改善。完了予定：2026年3月。

v0.9：Linux、スマートフォンを含むマルチシステム対応の改善。猫娘ネットワーク公開。完了予定：2026年4月。

v1.0：一部モデルプロバイダーへの対応を廃止し、自社大規模モデルとエージェントシステムに注力。完了予定：2026年6月。

テレメトリ (Telemetry)

N.E.K.O. は匿名の LLM トークン利用テレメトリをデフォルトで有効にしています。バージョン互換性・モデル利用分布・エラー率を把握するためです。「データで製品を改善する」ことの必要性は認めますが、それ以上に「ユーザーに隠れて何かを集めない」ことを大切にしています。

ワンライナー オプトアウト：環境変数 DO_NOT_TRACK=1（または NEKO_DO_NOT_TRACK=1）を設定すれば、再ビルド不要で即座にテレメトリは完全停止します。これはオープンソースコミュニティ標準の Console Do Not Track 規約に従っています。

収集する / しないもの：

仮名化デバイス識別子について：一方向 SHA-256、不可逆、ユーザー情報を含みません。同一マシン（同一 OS インストール）で同じ識別子が再生成されるため、GDPR / PIPL の分類では「完全な匿名データ」ではなく仮名化識別子に該当します。重複排除した DAU 集計とバージョン互換性の帰属分析のみに使用します。

Steam64 について：Steam クライアントがログイン後に任意のサードパーティ SDK に公開する数字 ID です（あなたの Steam プロフィール URL 末尾の数字がまさにそれです）。メール・電話番号・本名は含みませんが、セッションをまたいで安定します。実際のトリガー条件は配布ラベルではなくコードに従います：app/main_server.py は起動時に無条件で initialize_steamworks() を呼び、utils/token_tracker.py の _get_telemetry_steam_user_id() は source / release / steam という配布チャネルを区別せず、SDK が起動して非ゼロの Steam ID を返せばそれを送信します。典型的には Steam 配布版ですが、ソース版でも steamworks Python パッケージがインストールされ steam_appid.txt が残っており Steam クライアントにログイン中であれば、Steam64 が送信されます。送信を避けたい場合：(1) 最も確実な方法は DO_NOT_TRACK=1 で全停止；(2) Steam クライアントからログアウト；(3) ソース版利用者は steamworks パッケージをアンインストールするか作業ディレクトリから steam_appid.txt を削除してください。

実装とプロトコルの詳細は utils/token_tracker.py および local_server/telemetry_server/README.md を参照：HMAC-SHA256 署名・±5 分のリプレイ防止ウィンドウ・スライディングウィンドウ制限（120 req/h/device）・追記専用ストレージ。各サーバープロセスは最大で約 60 秒に 1 回の送信（ローカルディスクへの書き出しと同じスロットルタイマーを共有）で、メイン処理には影響しません。