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
```
Para usuarios que desean aislar la CLI del sistema Python. La actualización y la desinstalación también son relativamente claras y son las rutas recomendadas para versiones estables.
### pipa
```bash
python -m pip install nanobot-ai
```
Debe ejecutarse en un entorno virtual. No fuerce la instalación de Python en su sistema, especialmente no omita `externally-managed-environment` con privilegios de administrador.
### Instalación del código fuente
La versión del código fuente tiene funciones actualizadas, pero puede requerir `bun` o `npm` para crear la WebUI, y la configuración y los comandos también cambian más rápido que el paquete estable. Elija el código fuente solo si necesita las funciones más recientes o participar en el desarrollo.
## Qué creará `onboard`
Ejecutar:
```bash
nanobot onboard --wizard
```
Generado principalmente:
- `~/.nanobot/config.json`: Configuración de proveedor, modelo, agente y herramienta;
- `~/.nanobot/workspace/`: Espacio de trabajo del agente, memoria y archivos relacionados.
Después de completar el asistente, primero haga una copia de seguridad de una plantilla de configuración que no contenga la clave real. Cuando modifique la configuración en el futuro, utilice el método de combinación. No copie todo el contenido generado por el asistente de cobertura JSON en el tutorial.
## Explicación detallada de los ajustes preestablecidos de proveedor y modelo
La configuración suele dividirse en dos niveles:
```text
providers：怎样连接服务，包括 API Key 和 API Base
modelPresets：使用哪个 Provider、模型 ID 和参数
```
Un ejemplo conceptual:
```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
}
}
}
```
La configuración real debe fusionarse en el archivo existente. `contextWindowTokens` no se puede escribir arbitrariamente como un valor grande y debe ser coherente con el modelo real del Proveedor; de lo contrario, las tareas largas pueden fallar en el lado del servidor.
## Cinco niveles de primera verificación
### 1. Estado de configuración
```bash
nanobot status
```
Confirme la configuración, el espacio de trabajo y el proveedor actual. Mostrar `not set` sin un proveedor no indica un error.
### 2. Mensaje único
```bash
nanobot agent -m "只回复当前模型名称，不调用任何工具。"
```
Primero verifique la conexión del modelo. No abra Shell, Search y MCP juntos.
### 3. Sesión interactiva
```bash
nanobot agent
```
Compruebe que las múltiples rondas de contexto, salida y recuperación sean las esperadas.
### 4. Interfaz de usuario web
Inicie la puerta de enlace y acceda a `127.0.0.1:8765` para verificar la lista de sesiones, la configuración y el espacio de trabajo sin abrir primero la LAN.
### 5. Una herramienta de solo lectura
Finalmente, agregue un MCP o una herramienta web de solo lectura y observe las llamadas a herramientas, los registros y el manejo de errores. No considere los permisos de escritura hasta que haya terminado.
## No confunda los puertos WebUI y Gateway
Camino estable:
```bash
nanobot gateway
```
Acceso al navegador:
```text
http://127.0.0.1:8765
```
`18790` es principalmente un puerto de verificación de estado, no WebUI. Si no se puede abrir la página, primero verifique el registro de la puerta de enlace y el estado de escucha de `8765`. No exponga ambos puertos a la red pública.
Para ejecutar en segundo plano puedes usar:
```bash
nanobot gateway --background
nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop
```
Antes de ejecutar durante mucho tiempo, confirme la ubicación del registro, el inicio automático y la recuperación de salida anormal.
## Accede a los ítems de cheques de Ollama
Ollama se puede conectar a través de una interfaz nativa compatible con OpenAI, pero al menos verifique:
- Si se puede acceder a la API Base desde el proceso del nanobot;
- El ID del modelo es coherente con `ollama list`;
- Si el modelo puede soportar de manera confiable llamadas a herramientas;
- Si la configuración de la longitud del contexto es verdadera;
- Si la concurrencia agotará la memoria de vídeo;
- Si Gateway y Ollama solo escuchan redes confiables.
Pruebe primero las conversaciones normales y luego pruebe las herramientas individuales. Si un modelo devuelve una llamada de herramienta que parece JSON pero no tiene un formato válido, el problema puede estar relacionado con las capacidades del modelo o la compatibilidad de la plantilla.
## Cómo autorizar el servidor MCP en diferentes niveles
| Tipo | Recomendaciones de permisos iniciales |
| --- | --- |
| Consulta de documentos | Solo lectura, se puede habilitar primero |
| Archivos locales | Espacio de trabajo limitado, inicio de sólo lectura |
| Navegador | Usando el perfil de prueba |
| Base de datos | Cuenta de sólo lectura y biblioteca de pruebas |
| Concha | Entorno independiente de bajos privilegios |
| Plataforma en la nube | IAM mínimo, credenciales de corta duración |
Lea el código fuente del servidor y la lista de herramientas antes de la instalación. Los comandos, las variables de entorno y las URL que aparecen en una configuración de MCP se consideran parte de la cadena de suministro ejecutable.
## ¿Qué debería almacenarse en la memoria a largo plazo?
La memoria es adecuada para guardar preferencias estables, compromisos de proyectos e información que el usuario solicita explícitamente conservar. No es adecuado para guardar automáticamente:
- Clave API y contraseña;
- Código de verificación único;
- Datos originales del cliente;
- Inferencia de modelo no confirmada;
- Grandes secciones de contenido que se pueden volver a leer desde el archivo del proyecto;
- Estado de tarea temporal caducada.
Después de la activación, verifique periódicamente los archivos de memoria para confirmar que el mecanismo de eliminación y corrección sea efectivo. Los errores de memoria a largo plazo se amplifican repetidamente en tareas posteriores.
## Secuencia de acceso a la aplicación de chat
Primero use un bot de prueba y una cuenta de la lista blanca que solo lo permita usted mismo, y luego abra el chat grupal. Es necesario confirmar cada canal:
1. ¿Quién puede enviar mensajes al robot?
2. Si los miembros del grupo pueden activar la herramienta;
3. ¿Dónde se guardan los archivos adjuntos?
4. Si se debe hacer eco del registro interno;
5. Quién crea y cancela tareas programadas;
6. Cómo restaurar el robot después de que esté fuera de línea;
7. Si la plataforma de chat guarda copias de los mensajes.
La comodidad del chat no sustituye al control de identidad y permisos.
## Reglas de seguridad automatizadas programadas
Los objetivos a largo plazo y las tareas cron deben tener:
- Aclarar la frecuencia de funcionamiento;
- Tiempo máximo de ejecución;
- Tarifa máxima de modelo;
- Límite del número de llamadas a herramientas;
- Mecanismo idempotente o de deduplicación;
- Notificación de fallo;
- Interruptor de parada manual;
- No utilice reintentos infinitos.
Realice resúmenes de solo lectura solo cuando cree la automatización por primera vez y luego permita la escritura de archivos o el envío de mensajes después de algunas rondas de observación.
## Lista de verificación de implementación de red pública
Si debe acceder a la WebUI a través del servidor:
- Establecer `NANOBOT_WEB_TOKEN` aleatorio fuerte;
- Utilice proxy inverso HTTPS;
- Exponer sólo los puertos necesarios;
- Restringir la IP de origen o utilizar VPN;
- Configuración, espacio de trabajo y memoria persistentes;
- No escriba la clave en la imagen;
- Restringir los permisos y el montaje de los contenedores;
- Configurar la rotación y la copia de seguridad de registros;
- Grabar versiones y probar la recuperación antes de actualizar.
Las implementaciones con un solo clic para plataformas como Render también requieren discos persistentes; de lo contrario, es posible que se pierdan sesiones y memoria con las reconstrucciones de instancias.
## Matriz de solución de problemas
| Fenómeno | Causas comunes | Métodos de tratamiento |
| --- | --- | --- |
| `nanobot` no encontrado | Directorio de herramientas no en RUTA | Utilice `uv tool run` o corrija PATH |
| 401 | Error de configuración de clave o proveedor | Marque `providers` |
| El modelo 404 no existe | El ID del modelo o la base API no coinciden | Consulte la lista de modelos de servidores |
| No se puede abrir WebUI | Confusión de puerto o puerta de enlace no iniciada | Verifique 8765 y registros |
| Error de formato de llamada de herramienta | El modelo no es compatible o la plantilla es incompatible | Reemplazar el modelo que soporta la herramienta |
| La sesión desapareció después del reinicio | Espacio de trabajo no persistido | Comprobar disco y montar |
| El chatbot no responde | Token, lista blanca o puerta de enlace | Registros jerárquicos del canal de inspección |
| Ejecución repetida de tareas programadas | Falta de registros de idempotencia y estatus | Agregar claves de deduplicación y bloqueos de ejecución |
## Preguntas frecuentes
### ¿Qué debo hacer si `nanobot` no está en PATH?
Utilice el comando de inicio correspondiente al método de instalación, por ejemplo:
```bash
uv tool run --from nanobot-ai nanobot --version
```
También puede verificar si `uv tool` o el directorio ejecutable del entorno virtual se han agregado a `PATH`.
### WebUI no se puede abrir pero el control de estado es normal
El puerto predeterminado de WebUI es `8765`; El puerto `18790` de Gateway se utiliza principalmente para comprobar el estado, no para la interfaz del navegador. Confirme la dirección de escucha real y el registro de errores en el terminal.
### ¿Puedo recoger a Ollama directamente?
Se puede configurar a través de la interfaz nativa compatible con OpenAI, pero verifique que el modelo admita el formato de llamada de herramienta, la longitud del contexto y la simultaneidad requeridos. El éxito de las conversaciones ordinarias no significa que MCP y las llamadas a herramientas complejas sean necesariamente estables.
### ¿Cuál es la diferencia entre `nanobot webui` y `nanobot gateway`?
Las versiones estables prefieren usar `gateway` y abrir la página manualmente; Las versiones más recientes del código fuente pueden proporcionar el comando `webui` para preparar automáticamente el canal y abrir el navegador. Prevalecerá la información de ayuda de la versión actualmente instalada.
### ¿Pueden varias personas compartir el mismo nanobot?
Es necesario verificar que los permisos de usuario, sesión, espacio de trabajo y herramientas estén realmente aislados. Úselo como Agente de usuario único antes de confirmar y no confíe únicamente en los apodos del chat para distinguir los permisos.
### ¿Cómo hacer una copia de seguridad?
Haga una copia de seguridad de las plantillas de seguridad, los espacios de trabajo, los recuerdos y los datos de sesión necesarios de `~/.nanobot/config.json`. Es mejor reinyectar la clave real mediante la administración de claves y no ingresarla en una copia de seguridad normal.
### ¿Qué debo hacer si la configuración falla después de la actualización?
Primero verifique los cambios de versión y las instrucciones de migración, use la copia de seguridad para restaurar y luego combine las configuraciones una por una. No sobrescriba la estructura predeterminada generada por la nueva versión con la sección completa del archivo anterior.
## Resumen
La ventaja del nanobot es que tiene un núcleo más pequeño y además cuenta con WebUI, memoria, MCP, automatización y portal de chat. El método de implementación más seguro es comenzar desde la terminal local, abrir funciones y alcances de red capa por capa y establecer límites de permisos para herramientas, canales de chat y memoria a largo plazo.
|