# 运行机器人

***

## 启动机器人

在你的虚拟环境已激活且 `.env` 已配置：

```bash
python -m bot.main
```

成功启动后，你应该会看到如下控制台输出：

```
已登录为 Verbal Warning Logger#1234（ID：123456789012345678）
```

***

## 首次运行行为

在第一次运行时，机器人会自动：

* 创建 `warnings.db` — 用于口头警告的 SQLite 数据库
* 创建 `staffpolls.db` — 用于投票和模板的 SQLite 数据库
* 初始化所有表结构
* 与 Discord 全局同步斜杠命令

> **全局命令同步最多可能需要一小时** 才能传播到所有服务器。待 Discord 的缓存更新后，命令就会出现在你的服务器中。

***

## 开发期间更快同步命令

要让斜杠命令立即在单个服务器中显示（测试时很有用），请编辑 `bot/main.py` 并替换其中的同步行 `setup_hook`:

```python
# 将此替换为：
await self.tree.sync()

# 使用此替换（将其中的服务器 ID 替换为你的）：
await self.tree.sync(guild=discord.Object(id=YOUR_GUILD_ID))
```

命令会在几秒内出现在该 guild 中。请记住，如果你希望机器人在多个服务器中工作，在部署到生产环境之前要还原此更改。

***

## 保持机器人持续运行

对于生产部署，你应该将机器人作为后台服务运行，以便在终端断开连接和服务器重启后仍能继续运行。

### systemd（Linux）

创建 `/etc/systemd/system/verbal-warning-logger.service`:

```ini
[Unit]
Description=Verbal Warning Logger Discord Bot
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/verbal-warning-logger
ExecStart=/path/to/verbal-warning-logger/.venv/bin/python -m bot.main
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

然后启用并启动它：

```bash
sudo systemctl daemon-reload
sudo systemctl enable verbal-warning-logger
sudo systemctl start verbal-warning-logger
```

使用以下命令查看日志：

```bash
sudo journalctl -u verbal-warning-logger -f
```

### pm2（任意平台）

```bash
pm2 start "python -m bot.main" --name verbal-warning-logger --interpreter python3
pm2 save
pm2 startup
```

***

## 停止机器人

发送 `Ctrl+C` 在终端中，或者如果作为服务运行：

```bash
sudo systemctl stop verbal-warning-logger
# 或
pm2 stop verbal-warning-logger
```

***

## 故障排除

| 症状                         | 可能原因                                |
| -------------------------- | ----------------------------------- |
| `KeyError: DISCORD_TOKEN`  | `.env` 文件缺失，或不在项目根目录中               |
| 命令未显示                      | 全局同步仍在传播——最多等待 1 小时，或者使用 guild 同步   |
| `/auttaja` 命令缺失            | `SUPABASE_URL` / `SUPABASE_KEY` 未设置 |
| `discord.errors.Forbidden` | 机器人在频道或服务器中缺少所需权限                   |
| 在以下位置出现权限错误 `/verbal`      | 用户的最高角色低于 `STAFF_ROLE_ID` 在角色列表中    |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vigila.augystudios.com/zh/zi-tuo-guan/running.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.