概要
- ClawdbotからMoltbotへのリブランドに伴うガイドライン修正
- プロジェクト構成、ビルド・テスト手順、セキュリティポリシーの詳細
- プラグイン管理、開発・運用フロー、各種コマンドの統一
- macOS、モバイル、VMなど各環境固有の注意点
- バージョン管理・リリース・トラブルシューティングの重要ポイント
Moltbotリポジトリ運用ガイドライン
- リポジトリURLは https://github.com/moltbot/moltbot3 に統一
- GitHubのIssue/コメント/PRでは リテラル複数行文字列 （
-F - <<'EOF'や$'...'）を使用、\n埋め込み禁止 - ソースコードは
src/配下に整理- CLIは
src/cli、コマンドはsrc/commands、Webプロバイダーはsrc/provider-web.ts、インフラはsrc/infra、メディアパイプラインはsrc/media
- CLIは
- テストは各ファイル隣接の
*.test.ts形式 - ドキュメントは
docs/、ビルド成果物はdist/ - プラグイン・拡張は
extensions/*に格納- 依存関係は各extensionの
package.jsonに記載、本体利用時のみルートに追加 - プラグインのインストールは
npm install --omit=devで実行し、runtime依存はdependenciesに必ず記載 workspace:*依存は避け、moltbotはdevDependenciesまたはpeerDependenciesに
- 依存関係は各extensionの
- インストーラは
https://molt.bot/*で配布、実体は../molt.botリポジトリ管理 - ルーティングやallowlist等の共通ロジック修正時は 全チャネル（内蔵＋拡張） を考慮
Moltbotプロジェクト構成・モジュール整理
- コアチャネルのドキュメントは
docs/channels/に格納 - コードコメントは 難解・分かりづらい箇所 に必ず追加
- 1ファイルあたり 700行未満 を目安に分割・リファクタリング
- 命名規則
- 製品名/ドキュメント見出しは Moltbot
- CLIコマンド・パス・設定キーは
moltbot小文字
exe.dev VM運用
- 安定したアクセスは
ssh exe.dev→ssh vm-name（SSH鍵設定済み前提） - SSH不安定時は WebターミナルまたはShelley 利用、長時間処理はtmux推奨
- Moltbot更新は
sudo npm i -g moltbot@latest（グローバルインストールはroot権限必須） - 設定変更は
moltbot config set ...、gateway.mode=local必須 - Discordトークンは 生値のみ保存 （プレフィックス禁止）
- ゲートウェイ再起動例
pkill -9 -f moltbot-gateway || true; nohup moltbot gateway run --bind loopback --port 18789 --force > /tmp/moltbot-gateway.log 2>&1 &
- 動作確認コマンド
moltbot channels status --probess -ltnp | rg 18789tail -n 120 /tmp/moltbot-gateway.log
ビルド・テスト・開発コマンド
- 実行環境は Node 22+、Node/Bun両対応
- 依存インストールは
pnpm install、プリコミットフックはprek install - BunによるTypeScript実行推奨
- スクリプト・開発・テスト：
bun <file.ts>/bunx <tool>
- スクリプト・開発・テスト：
- CLI開発時は
pnpm moltbot ...またはpnpm dev - 本番運用・ビルド済みはNode対応
- Macアプリパッケージングは
scripts/package-mac-app.sh（現アーキテクチャデフォルト） - 型チェック・ビルドは
pnpm build
テストとリリース
- テスト命名は実装ファイル名と一致、E2Eは
*.e2e.test.ts - ロジック修正時は
pnpm test実行必須 - テストワーカー数は 16以下
- ライブテスト例
- Moltbot単体：
CLAWDBOT_LIVE_TEST=1 pnpm test:live - プロバイダー含む：
LIVE=1 pnpm test:live - Docker関連：
pnpm test:docker:live-modelsなど
- Moltbot単体：
- 純粋なテスト追加・修正は原則Changelog不要（ユーザー影響時のみ記載）
セキュリティ・設定の注意点
- Webプロバイダーの認証情報は
~/.clawdbot/credentials/（Moltbotでもパスは変更なし） - Piセッションは
~/.clawdbot/sessions/（ベースディレクトリ固定） - 環境変数は
~/.profile参照 - 実際の電話番号・動画・本番設定値は 絶対にコミット/公開禁止、テスト用ダミー値を使用
- リリース作業前に
docs/reference/RELEASING.mdとdocs/platforms/mac/release.md必読
トラブルシューティング
- リブランド・移行やレガシー設定警告時は
moltbot doctor実行 - エージェント固有の注意点やノウハウは
tools.mdやAGENTS.mdに記録 - Signalの更新コマンド例
fly ssh console -a flawd-bot -C "bash -lc 'cd /data/clawd/moltbot && git pull --rebase origin main'"fly machines restart e825232f34d058 -a flawd-bot
- GitHub Issue/PR作業時は URLを必ず最後に出力
macOS・モバイル・バージョン管理
- ゲートウェイは Moltbot Macアプリのみで動作、LaunchAgent/ヘルパーは未提供
- 再起動はMacアプリまたは
scripts/restart-mac.shで実施 - ログ取得は
./scripts/clawlog.sh（Moltbotサブシステム指定、sudo不要設定推奨） - バージョン管理ファイル例
package.json（CLI）apps/macos/Sources/Moltbot/Resources/Info.plistdocs/install/updating.mdなど
- iOS/Androidアプリの再起動は 再ビルド・再インストール・再起動
- 実機優先でテスト（シミュレータは補助）
開発・運用フローのベストプラクティス
- 依存パッチ適用は 明示的な承認が必要
- CLI進捗表示は
src/cli/progress.ts（osc-progress＋@clack/prompts）を利用 - ステータス出力は
src/terminal/table.ts、status --allは貼り付け用・status --deepは詳細プローブ - SwiftUIは
Observationフレームワーク推奨、ObservableObjectは最小限 - 新規コネクション追加時は 全UI・ドキュメント・設定反映必須
このガイドラインに従うことで、 Moltbot プロジェクトの一貫性・保守性・セキュリティを維持可能。各項目の詳細は該当ドキュメントを参照。