AI Agent Engineer

AI Agent Engineer

nanobot 配置与环境变量索引

6 min read

nanobot 配置与环境变量索引

对应源码

控制面源码
配置路径与加载nanobot/config/paths.py、nanobot/config/loader.py::load_config
环境变量展开nanobot/config/loader.py::resolve_config_env_vars
字段、默认值和验证nanobot/config/schema.py
Agent/Runner 行为nanobot/agent/loop.py、nanobot/agent/runner.py
Provider、Tool、Channel 读取nanobot/providers/、nanobot/agent/tools/、nanobot/channels/

本页只收录学习源码和调试时最常用的控制点。完整字段、Provider 和 Channel 配置请查 官方 Configuration 文档 与 nanobot/config/schema.py。

1. 配置从哪里来

flowchart LR
    F["配置文件"] --> L["load_config()"]
    L --> P["Pydantic Config"]
    P --> E["resolve_config_env_vars()"]
    E --> R["Provider / AgentLoop / Gateway / Tools"]

关键源码：

  • nanobot/config/paths.py：配置和 workspace 路径；
  • nanobot/config/loader.py::load_config：读取与解析；
  • nanobot/config/loader.py::resolve_config_env_vars：递归替换字符串中出现的 ${VAR}；
  • nanobot/config/schema.py：字段、默认值、别名和验证。

不要在日志或笔记里打印 key

配置可写成 "apiKey": "${DEEPSEEK_API_KEY}"。若变量不存在，解析阶段会报错；排查时只确认变量是否存在，不输出它的值。

2. Agent 默认行为

配置路径均以序列化后的 camelCase 形式表达。

配置路径默认值控制边界主要读取位置
agents.defaults.workspace~/.nanobot/workspaceSession、Memory、Skills 和文件类工具的工作根AgentDefaults、runtime 组装
agents.defaults.modelPresetnull有值时优先使用命名 presetnanobot/agent/model_presets.py
agents.defaults.modelanthropic/claude-opus-4-5未使用 preset 时的默认模型Provider snapshot 构建
agents.defaults.providerauto显式 Provider 或自动检测nanobot/providers/factory.py
agents.defaults.maxTokens8192单次生成上限generation settings
agents.defaults.contextWindowTokens200000上下文预算与压缩判断Context/compaction
agents.defaults.maxToolIterations200Runner 模型—工具循环上限AgentRunner
agents.defaults.maxConcurrentSubagents1同一 runtime 可并发的 subagent 数Subagent manager
agents.defaults.maxToolResultChars16000回填模型的工具结果字符上限Runner/tool result 处理
agents.defaults.providerRetryModestandard标准或持续重试策略Provider 调用边界
agents.defaults.reasoningEffortnull传给支持该能力的 Providergeneration settings
agents.defaults.timezoneUTCCron、时间提示等时区语义Loop/Cron
agents.defaults.unifiedSessionfalse是否跨 Channel 共用 Sessionnanobot/session/keys.py
agents.defaults.disabledSkills[]禁止加载哪些 SkillSkillsLoader
agents.defaults.idleCompactAfterMinutes15空闲多久后允许压缩，0 禁用AgentLoop
agents.defaults.maxMessages120回放历史条数上限；0 仍使用默认 120Session/Context
agents.defaults.consolidationRatio0.5压缩后希望保留的预算比例Consolidator
agents.defaults.dream.enabledtrue是否注册 Dream 周期任务Dream/Gateway
agents.defaults.dream.intervalH2默认 Dream 间隔DreamConfig.build_schedule()

3. 模型与 Provider

配置区域作用
modelPresets.<name>命名组合：model、provider、maxTokens、contextWindowTokens、temperature、reasoningEffort
providers.<name>.apiKeyProvider 凭据，可引用 ${VAR}
providers.<name>.apiBase自定义服务地址
providers.<name>.extraHeaders附加 HTTP header
providers.<name>.extraBody附加请求 body
providers.<name>.extraQuery附加 query 参数
providers.openai.apiTypeauto、chat_completions 或 responses；当前只允许用于内置 OpenAI 配置

DeepSeek 的注册事实位于 nanobot/providers/registry.py：

Provider 名：deepseek
默认凭据环境变量：DEEPSEEK_API_KEY

其他 Provider 的 key 和默认 endpoint 应直接查 registry，不要从名称猜：

rg -n "ProviderSpec|env_key=|api_base=" nanobot/providers/registry.py

4. Tool、安全和 MCP

配置路径作用注意
tools.restrictToWorkspace启用应用层 workspace 限制意图不自动等于 OS sandbox
tools.exec.*shell 执行、超时、路径和 sandbox 相关配置以 nanobot/agent/tools/shell.py::ExecToolConfig 为准
tools.file.*文件工具配置以 nanobot/agent/tools/filesystem.py::FileToolsConfig 为准
tools.web.*搜索和抓取配置以 nanobot/agent/tools/web.py::WebToolsConfig 为准
tools.mcpServers.<name>stdio、SSE 或 Streamable HTTP MCP 连接见下表
tools.ssrfWhitelist允许绕过 SSRF 阻断的 CIDR只添加明确可信范围
tools.webuiAllowLocalServiceAccessWebUI Full Access 下是否允许检查 localhost 服务不应理解为全局关闭 SSRF

一个 MCP server 的核心字段：

字段含义
typestdio、sse、streamableHttp；省略时自动判断
command、args、env、cwdstdio 进程
url、headers网络 transport
toolTimeout单次 MCP Tool 超时，默认 30 秒
enabledTools允许注册的工具；["*"] 表示全部，[] 表示不注册

5. Channel、API 与 Gateway

配置路径默认值说明
channels.sendProgresstrue是否向 Channel 发送文本进度
channels.sendToolHintsfalse是否发送工具提示
channels.showReasoningtrueChannel 实现支持时是否显示 reasoning
channels.extractDocumentTexttrue是否预提取文档附件文本
channels.sendMaxRetries3投递总尝试次数，包含第一次
channels.<name>.*由各 Channel 定义ChannelsConfig 允许额外字段
api.host / api.port127.0.0.1 / 8900OpenAI-compatible API
api.timeout120.0每个 API 请求超时秒数
gateway.host / gateway.port127.0.0.1 / 18790Gateway/WebUI 服务
gateway.heartbeat.*见 HeartbeatConfigHeartbeat 的启用、间隔和保留消息数

6. 调试时最重要的环境变量

环境变量默认/语义读取位置
DEEPSEEK_API_KEYDeepSeek 凭据Provider registry/config 解析
NANOBOT_MAX_CONCURRENT_REQUESTS默认 3；<=0 表示不设全局并发上限nanobot/agent/loop.py
NANOBOT_LLM_TIMEOUT_S默认 300 秒；0 禁用 Runner 外层 LLM wall timeoutnanobot/agent/runner.py
NANOBOT_STREAM_IDLE_TIMEOUT_S默认 90 秒，最大 3600；无效或非正数回退默认值nanobot/providers/base.py
NANOBOT_OPENAI_COMPAT_TIMEOUT_S默认 120 秒；无效或非正数回退默认值nanobot/providers/openai_compat_provider.py
NANOBOT_WORKSPACE_SANDBOX_PROVIDER记录/指定 workspace sandbox provider 语义nanobot/security/workspace_access.py
NANOBOT_WORKSPACE_SANDBOX_ENFORCED标记 sandbox 是否强制同上
NANOBOT_SANDBOX_ENFORCED兼容性环境标记同上

三种“超时”不是同一层

api.timeout 管 HTTP 请求，NANOBOT_LLM_TIMEOUT_S 管一次 Runner 的模型等待边界，NANOBOT_STREAM_IDLE_TIMEOUT_S 管流已经开始后的空闲停顿。定位超时时先确认是哪一层报错。

7. 配置没有生效时

按以下顺序检查：

  1. 运行进程实际加载了哪个配置路径；
  2. 字段名是否被 schema 接受，别名是否正确；
  3. ${VAR} 是否在启动进程的环境中存在；
  4. modelPreset 是否覆盖了散列的 model/provider 字段；
  5. Gateway 是否需要重启或 runtime refresh；
  6. 修改的是全局 Channel 字段还是某个 Channel 的覆盖字段；
  7. 日志显示的 active Provider/model 是否与预期一致。

返回：速查参考

Backlinks