nanobot ローカル展開チュートリアル: WebUI、モデル構成、MCP、チャット アプリケーション アクセス

1

uv tool install nanobot-ai

1

python -m pip install nanobot-ai

1
2

nanobot --version
nanobot onboard --wizard

1

nanobot gateway

1

http://127.0.0.1:8765

1

nanobot webui

1
2

nanobot status
nanobot agent -m "Hello!"

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264

uv tool install nanobot-ai
```

CLI をシステム Python から分離したいユーザー向け。アップグレードとアンインストールも比較的明確であり、安定バージョンの推奨パスです。

### ピップ

```bash
python -m pip install nanobot-ai
```

仮想環境で実行する必要があります。システムに Python を強制的にインストールしないでください。特に、管理者権限で `externally-managed-environment` をバイパスしないでください。

### ソースコードのインストール

ソース コード バージョンには更新された機能がありますが、WebUI を構築するには `bun` または `npm` が必要な場合があり、構成とコマンドも安定したパッケージよりも速く変更されます。最新の機能が必要な場合、または開発に参加する場合にのみソース コードを選択してください。

## `onboard` が作成するもの

実行:

```bash
nanobot onboard --wizard
```

主に生成されるもの:

- `~/.nanobot/config.json`: プロバイダー、モデル、エージェント、およびツールの構成。
- `~/.nanobot/workspace/`: エージェントのワークスペース、メモリ、および関連ファイル。

ウィザードが完了したら、最初に実際のキーが含まれていない構成テンプレートをバックアップします。将来的に構成を変更する場合は、マージ方法を使用してください。 JSON カバレッジ ウィザードで生成されたチュートリアルのコンテンツ全体をコピーしないでください。

## プロバイダーとモデルのプリセットの詳細な説明

構成は通常、次の 2 つのレベルに分かれています。

```text
providers：怎样连接服务，包括 API Key 和 API Base
modelPresets：使用哪个 Provider、模型 ID 和参数
```

概念的な例:

```json
{
  "providers": {
    "custom": {
      "apiKey": "your-api-key",
      "apiBase": "https://api.example.com/v1"
    }
  },
  "modelPresets": {
    "primary": {
      "label": "Primary",
      "provider": "custom",
      "model": "model-id-from-your-provider",
      "maxTokens": 8192,
      "contextWindowTokens": 200000,
      "temperature": 0.1
    }
  }
}
```

実際の設定は既存のファイルにマージする必要があります。 `contextWindowTokens` は任意に大きな値として書き込むことはできず、プロバイダーの実際のモデルと一致している必要があります。そうでないと、サーバー側で長いタスクが失敗する可能性があります。

## 最初の検証の 5 つのレベル

### 1. 構成ステータス

```bash
nanobot status
```

構成、ワークスペース、現在のプロバイダーを確認します。プロバイダーなしで `not set` を表示しても、エラーは示されません。

### 2. 単一メッセージ

```bash
nanobot agent -m "只回复当前模型名称，不调用任何工具。"
```

まずモデルの接続を確認してください。シェル、検索、MCP を同時に開かないでください。

### 3. インタラクティブセッション

```bash
nanobot agent
```

コンテキスト、終了、およびリカバリの複数のラウンドが期待どおりであることを確認します。

### 4. WebUI

ゲートウェイを起動し、`127.0.0.1:8765` にアクセスして、最初に LAN を開かずにセッション リスト、設定、およびワークスペースを確認します。

### 5. 読み取り専用ツール

最後に、読み取り専用の MCP または Web ツールを追加し、ツールの呼び出し、ログ、エラー処理を観察します。完了するまでは書き込み権限について考慮しないでください。

## WebUI ポートとゲートウェイ ポートを混同しないでください

安定したパス:

```bash
nanobot gateway
```

ブラウザアクセス:

```text
http://127.0.0.1:8765
```

`18790` は主にヘルス チェック ポートであり、WebUI ではありません。ページを開けない場合は、まずゲートウェイ ログと `8765` リスニング ステータスを確認してください。両方のポートをパブリック ネットワークに公開しないでください。

バックグラウンドで実行するには、次を使用できます。

```bash
nanobot gateway --background
nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop
```

長時間実行する前に、ログの場所、自動起動、異常終了の回復を確認してください。

## オラマのチェック項目にアクセスする

Ollama はネイティブの OpenAI 互換インターフェイス経由で接続できますが、少なくとも以下を確認してください。

- API ベースがナノボット プロセスからアクセス可能かどうか。
- モデル ID は `ollama list` と一致します。
- モデルがツール呼び出しを確実にサポートできるかどうか。
- コンテキストの長さの設定が true であるかどうか。
- 同時実行によりビデオ メモリが枯渇するかどうか。
- Gateway と Ollama が信頼できるネットワークのみをリッスンするかどうか。

最初に通常の会話をテストし、次に個々のツールをテストします。モデルが JSON のように見えるツール呼び出しを返しますが、有効な形式ではない場合は、モデルの機能またはテンプレートの互換性に問題がある可能性があります。

## さまざまなレベルで MCP サーバーを認証する方法

|タイプ |初期権限の推奨事項 |
| --- | --- |
|ドキュメントクエリ |読み取り専用。最初に有効にすることができます。
|ローカルファイル |限られたワークスペース、読み取り専用で開始 |
|ブラウザ |テストプロファイルの使用 |
|データベース |読み取り専用アカウントとテスト ライブラリ |
|シェル |独立した低特権環境 |
|クラウドプラットフォーム |最小限の IAM、有効期間の短い認証情報 |

インストールする前に、サーバーのソース コードとツール リストをお読みください。 MCP 構成に含まれるコマンド、環境変数、および URL は、実行可能なサプライ チェーンの一部とみなされます。

## 何を長期記憶に保存すべきでしょうか?

メモリは、安定した設定、プロジェクトのコミットメント、およびユーザーが明示的に保持を要求した情報を保存するのに適しています。自動保存には適していません:

- API キーとパスワード;
- ワンタイム認証コード;
- 顧客のオリジナルデータ。
- 未確認のモデル推論。
- プロジェクト ファイルから再読み込みできるコンテンツの大部分。
- 一時タスクのステータスが期限切れになりました。

アクティブ化後は、メモリ ファイルを定期的にチェックして、削除および修正メカニズムが有効であることを確認してください。長期記憶エラーは、後続のタスクで繰り返し増幅されます。

## チャットアプリケーションのアクセスシーケンス

まず、テスト ボットと自分だけを許可するホワイトリスト アカウントを使用して、グループ チャットを開きます。各チャネルを確認する必要があります。

1. 誰がロボットにメッセージを送信できるか。
2. グループメンバーがツールをトリガーできるかどうか。
3. 添付ファイルはどこに保存されますか?
4. 内部ログをエコーするかどうか。
5. スケジュールされたタスクを作成およびキャンセルするのは誰ですか。
6. ロボットがオフラインになった後に復元する方法。
7. チャット プラットフォームがメッセージのコピーを保持するかどうか。

チャットの利便性は、ID と権限の制御に代わるものではありません。

## スケジュールされた自動セキュリティ ルール

長期的な目標と cron タスクには次のものが必要です。

- 動作周波数を明確にする。
- 最大実行時間。
- 最大モデル料金;
- ツール呼び出しの数の制限。
- 冪等または重複排除メカニズム。
- 失敗通知;
- 手動停止スイッチ;
- 無限に再試行しないでください。

最初にオートメーションを作成するときは読み取り専用の要約のみを実行し、数ラウンドの観察後にファイルの書き込みまたはメッセージの送信を許可します。

## パブリック ネットワーク導入チェックリスト

サーバー経由で WebUI にアクセスする必要がある場合:

- 強力なランダム `NANOBOT_WEB_TOKEN` を設定します。
- HTTPS リバース プロキシを使用します。
- 必要なポートのみを公開します。
- 送信元 IP を制限するか、VPN を使用します。
- 永続的な構成、ワークスペース、メモリ。
- イメージにキーを書き込まないでください。
- コンテナの権限とマウントを制限します。
- ログのローテーションとバックアップを構成します。
- アップグレード前にバージョンを記録し、リカバリをテストします。

Render などのプラットフォームのワンクリック デプロイメントにも永続ディスクが必要です。そうでないと、インスタンスの再構築でセッションとメモリが失われる可能性があります。

## トラブルシューティング マトリックス

|現象 |一般的な原因 |治療法 |
| --- | --- | --- |
| `nanobot` が見つかりません | Tools ディレクトリが PATH にありません | `uv tool run` を使用するか、PATH を修正してください。
| 401 |キーまたはプロバイダーの構成エラー | `providers` をチェック |
| 404 モデルは存在しません |モデル ID または API ベースが一致しません |サーバーモデルリストを確認する |
| WebUI を開けません |ポートの混乱またはゲートウェイが開始されていません。 8765 とログを確認する |
|ツール呼び出しフォーマットエラー |モデルがサポートされていないか、テンプレートに互換性がありません。ツールをサポートするモデルを置き換える |
|再起動後にセッションが消えた |ワークスペースが永続化されない |ディスクをチェックしてマウントする |
|チャットボットが応答しない |トークン、ホワイトリスト、またはゲートウェイ |階層的な検査チャネルのログ |
|スケジュールされたタスクの繰り返し実行 |冪等性とステータスレコードの欠如 |重複排除キーと実行ロックを追加する |

## よくある質問

### `nanobot` が PATH にない場合はどうすればよいですか?

インストール方法に対応する起動コマンドを使用します。例:

```bash
uv tool run --from nanobot-ai nanobot --version
```

`PATH` に `uv tool` または仮想環境の実行ディレクトリが追加されているかどうかも確認できます。

### WebUI を開けませんが、ヘルスチェックは正常です

WebUI のデフォルトのポートは `8765` です。ゲートウェイの `18790` ポートは、ブラウザ インターフェイスではなく、主にヘルス チェックに使用されます。実際のリスニングアドレスとエラーログを端末で確認してください。

### オラマを直接迎えに行くことはできますか?

ネイティブの OpenAI 互換インターフェイスを介して構成できますが、モデルが必要なツール呼び出し形式、コンテキストの長さ、同時実行性をサポートしていることを確認してください。通常の会話が成功しても、MCP や複雑なツールの呼び出しが必ずしも安定しているとは限りません。

### `nanobot webui` と `nanobot gateway` の違いは何ですか?

安定版リリースでは `gateway` を使用し、ページを手動で開くことを好みます。新しいソース コード バージョンでは、チャネルを自動的に準備してブラウザを開く `webui` コマンドが提供される場合があります。現在インストールされているバージョンのヘルプ情報が優先されます。

### 複数の人が同じナノボットを共有できますか?

ユーザー、セッション、ワークスペース、ツールの権限が本当に分離されていることを確認する必要があります。確認する前にシングルユーザー エージェントとして使用し、権限を区別するためにチャットのニックネームのみに依存しないでください。

### バックアップ方法は?

`~/.nanobot/config.json` のセキュリティ テンプレート、ワークスペース、メモリ、および必要なセッション データをバックアップします。本物のキーは、キー管理によって再挿入するのが最善であり、通常のバックアップには入力されません。

### 更新後に構成が失敗した場合はどうすればよいですか?

まず、バージョンの変更と移行手順を確認し、バックアップを使用して復元してから、構成を 1 つずつマージします。新しいバージョンによって生成されたデフォルトの構造を、古いファイルのセクション全体で上書きしないでください。

## 概要

nanobot の利点は、コアが小さく、WebUI、メモリ、MCP、自動化、チャット ポータルも備えていることです。最も安全な導入方法は、ローカル端末から開始して、機能とネットワーク スコープをレイヤーごとに開き、ツール、チャット チャネル、および長期メモリのアクセス許可の境界を設定することです。