高级配置
高级配置不是首次部署必须修改的内容。正常聊天已经可用后，再根据实际需要调整即可。
在哪里配置
进入 WebUI「系统配置」→「基本配置」，可以用页面搜索快速定位配置项名称。
什么时候需要改高级配置
| 场景 | 建议查看 |
|---|---|
| Bot 回复太频繁，想控制成本或防刷屏 | 回复配额 |
| 想控制哪些消息会触发 Bot | 触发与忽略规则 |
| 想让普通命令更好输入 | 命令体验 |
| 想排查 AI 为什么这样回复 | 调试与日志 |
| 上传文件太大，被系统拒绝 | 文件上传 |
| 图片识别效果不好或成本过高 | 视觉能力 |
| 请求模型服务需要代理 | 网络与代理 |
| 沙盒任务经常超时或并发不足 | 沙盒配置 |
| 需要使用危险管理命令 | 高级管理命令 |
回复配额
回复配额用于限制 Bot 在频道中的回复数量，适合控制调用成本、减少刷屏或保护公开频道。
| 配置项 | 默认值 | 说明 |
|---|---|---|
AI_CHAT_ENABLE_HOURLY_LIMIT | false | 启用每小时限额，让每日额度更均匀地分配到每个小时 |
AI_CHAT_QUOTA_SUPER_USERS_EXEMPT | true | 管理员不受回复配额限制 |
AI_CHAT_QUOTA_WHITELIST_USERS | [] | 白名单用户列表，列表中的用户不受回复配额限制 |
配额耗尽时
配额耗尽后，Bot 通常会直接不回复，而不是在群里提示“额度不足”。如果 Bot 突然变安静，可以先检查配额设置。
触发与忽略规则
触发规则决定 Bot 什么时候响应消息。公开群聊或消息量较大的频道中，建议根据实际需要控制触发范围。
常见配置包括：
| 类型 | 说明 |
|---|---|
| 触发正则 | 只有匹配指定规则的消息才更容易触发 Bot |
| 忽略正则 | 匹配指定规则的消息会被 Bot 忽略 |
| 随机回复 | 允许 Bot 在未被明确呼叫时按概率参与聊天 |
| 观察模式 | 只记录和观察消息，不主动回复 |
配置正则时建议先在小范围频道测试。规则过宽会导致 Bot 频繁回复，规则过窄则可能让正常消息无法触发。
频道级配置优先
如果只想调整某个群或频道，优先使用 频道管理 中的覆盖配置，不要直接修改全局规则。
命令体验
| 配置项 | 默认值 | 说明 |
|---|---|---|
COMMAND_MATCH_ALLOW_HYPHEN_FOR_UNDERSCORE | true | 允许用连字符代替下划线输入命令。例如 /na-info 可以匹配 /na_info |
建议保持默认开启。这样在手机端输入命令更方便。
调试与日志
这些配置主要用于排查问题。平时建议保持关闭，需要排查时再临时开启。
| 配置项 | 默认值 | 说明 |
|---|---|---|
SAVE_PROMPTS_LOG | false | 保存聊天提示词生成日志，方便排查 AI 收到了什么上下文 |
DEBUG_IN_CHAT | false | 在聊天中输出调试信息，适合临时定位问题 |
APP_LOG_LEVEL | INFO | 应用日志级别。需要更详细日志时可改为 DEBUG |
调试完成后建议关闭
调试日志可能包含较多上下文信息。问题排查完成后，建议关闭调试相关配置。
文件上传
| 配置项 | 默认值 | 说明 |
|---|---|---|
MAX_UPLOAD_SIZE_MB | 10 | 上传文件大小上限，单位 MB |
如果您经常让 AI 分析较大的图片、文档或表格，可以适当调大此值。
不建议盲目调得过大
上传上限越大，处理时间和资源占用也可能越高。建议只按实际需要调整。
视觉能力
视觉能力用于让 Bot 理解图片内容。它通常依赖支持图片输入的模型组。
常见需要关注的场景：
| 场景 | 建议 |
|---|---|
| 图片识别失败 | 检查当前模型是否支持视觉输入 |
| 图片太大或太多 | 调整上传限制，或让用户压缩后再发送 |
| 成本过高 | 限制图片触发场景，避免每张图都进入模型 |
| 群聊刷图 | 配合触发规则或频道覆盖配置限制响应 |
如果只是普通文字聊天，不需要开启或调整视觉相关配置。
网络与代理
当模型服务、插件接口或部分外部资源需要通过代理访问时，可以在系统配置中设置代理相关选项。
使用代理时建议确认：
- 代理地址能被 Nekro Agent 容器或运行环境访问
- 代理认证信息填写正确
- 不同服务是否需要走同一个代理
- 内网地址是否不应经过代理
如果代理配置错误，常见表现是模型请求超时、插件无法访问外部服务或更新检查失败。可以结合 日志中心 查看具体错误。
沙盒配置
沙盒用于执行 AI 生成的任务。大多数情况下保持默认即可。
| 配置项 | 默认值 | 适合什么时候改 |
|---|---|---|
SANDBOX_RUNNING_TIMEOUT | 120 | 普通沙盒任务经常没执行完就超时时调大 |
SANDBOX_MAX_CONCURRENT | 4 | 同时任务较多、机器资源足够时调大 |
SANDBOX_IMAGE_NAME | kromiose/nekro-agent-sandbox | 使用自定义普通沙盒镜像时修改 |
SANDBOX_CHAT_API_URL | 自动生成 | 沙盒无法访问 Nekro Agent API 时检查 |
SANDBOX_ONEBOT_SERVER_MOUNT_DIR | /app/nekro_agent_data | OneBot 协议端无法访问 NA 资源文件时检查 |
Claude Code 沙盒
如果您使用工作区和 Claude Code，还可能需要关注以下配置：
| 配置项 | 默认值 | 适合什么时候改 |
|---|---|---|
CC_SANDBOX_IMAGE | kromiose/nekro-cc-sandbox | 使用自定义 Claude Code 沙盒镜像时修改 |
CC_SANDBOX_IMAGE_TAG | latest | 固定或切换 CC 沙盒镜像版本时修改 |
CC_SANDBOX_PORT_RANGE_START | 40000 | 宿主机端口段被占用时调整 |
CC_SANDBOX_PORT_RANGE_END | 49999 | 宿主机端口段被占用时调整 |
CC_SANDBOX_STARTUP_TIMEOUT | 120 | CC 沙盒启动较慢、经常启动超时时调大 |
优先看工作区页面提示
如果是 Claude Code 沙盒启动失败，建议先查看工作区页面和沙盒日志，再决定是否调整这些配置。
高级管理命令
| 配置项 | 默认值 | 说明 |
|---|---|---|
ENABLE_ADVANCED_COMMAND | false | 启用高级管理命令 |
高级管理命令可能包含清理数据、删除工作区等高风险操作。只有在明确需要时才建议开启。
谨慎开启
开启后，请确保只有可信管理员可以使用相关命令。完成操作后，如无持续需求，建议关闭。
推荐调整顺序
如果您不确定该怎么调，建议按这个顺序：
- 先保持默认配置完成部署
- 确认 Bot 能正常聊天
- 根据频道规模设置回复配额
- 根据文件处理需求调整上传上限
- 根据频道规模配置触发和忽略规则
- 遇到问题时临时开启调试和日志
- 使用工作区后，再按需要调整 Claude Code 沙盒配置