NullClaw 配置实战：解读 `nullclaw onboard` 生成的 config.json（CONFIG.md 全解析）

人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP Clients【免费下载链接】nullclawFastest, smallest, and fully autonomous AI assistant infrastructure written in Zig项目地址https://gitcode.com/gh_mirrors/nu/nullclaw点击查看免费下载本篇技术指南围绕 NullClaw 工作区中的CONFIG.md文档展开它是一份由nullclaw onboard交互式向导自动生成的config.json 核心字段速查手册也是 Agent 每次对话时被注入系统提示的关键上下文。读完本文你将掌握 onboard 写入了哪些配置字段、每个字段的含义与默认值、自主性档位到配置项的映射规则以及渠道凭据与allow_from白名单的正确用法并能结合源码理解这些配置在运行时如何被解析和消费。CONFIG.md位于工作区脚手架模板目录 src/workspace_templates/CONFIG.md它有意只覆盖最常见的 onboarding 字段而非完整的 config schema原文档原文因此本文同样以这些字段为主线并补充底层实现证据。一、CONFIG.md 的定位Agent 的配置自述文件nullclaw onboard除了交互式地引导你完成 9 步配置流程外还会在工作区中落下一批引导文档SOUL.md、AGENTS.md、TOOLS.md、CONFIG.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md。从 src/onboard.zig 的scaffoldWorkspace可以看到CONFIG.md的内容由embedFile(workspace_templates/CONFIG.md)直接内嵌src/onboard.zig#L75并以storeOrWriteIfMissing方式写入工作区src/onboard.zig#L2930-L2931——即只在文件不存在时生成不会覆盖你后续的手工修改。这份文档并不是给人看的装饰文件而是Agent 自身的配置上下文在系统提示构建阶段src/agent/prompt.zig 会把工作区中的CONFIG.md注入系统提示相关测试见 src/agent/prompt.zig#L1622-L1642测试名buildSystemPrompt injects CONFIG.md when present让 Agent 随时知道自己运行在什么配置之下CONFIG.md被纳入工作区提示指纹workspacePromptFingerprint的追踪文件列表src/agent/prompt.zig#L235-L246一旦内容变化系统提示会基于 FNV1a-64 指纹重建对应测试workspacePromptFingerprint changes when CONFIG.md changes在基于 memory 的后端上CONFIG.md还对应一个逻辑文档键__bootstrap.prompt.CONFIG.md见 src/memory/root.zig#L351并会被 src/bootstrap/provider.zig#L74 的isBootstrapFilename识别为引导文档。一句话概括CONFIG.md 是 onboard 写给 Agent 自己的运行参数说明书。二、Core Fieldsonboard 落盘的核心字段原文档将 onboard 写入 config.json 的核心字段归纳为四个全部继承如下workspace用于本地文件与生成的引导文档bootstrap docs的工作区目录。onboard 的脚手架逻辑会在该目录下生成上文提到的全部引导文件并在目录内维护.nullclaw/workspace-state.json记录引导生命周期状态见 src/onboard.zig#L46-L48。models.providers.provider.api_keyprovider 凭据。只有在你在向导中输入了 key 时才会写入即使不写入环境变量方式依然生效。例如 config.example.json 中openrouter、nearai、atlas-cloud等都使用api_key: YOUR_XXX_API_KEY占位符格式。models.providers.provider.base_url自定义端点覆盖用于 custom / OpenAI 兼容 provider 以及类似的手动端点覆盖。示例配置中azure使用https://your-resource.openai.azure.comvertex则使用完整的 AI Platform 端点见 config.example.json#L18-L31。agents.defaults.model.primary默认模型路由格式为provider/model例如openrouter/anthropic/claude-sonnet-4config.example.json#L34-L40。在向导实现中provider 选择由known_providers表驱动src/onboard.zig#L101-L162覆盖 OpenRouter、Anthropic、OpenAI、Azure、Gemini、Vertex、DeepSeek、Groq、Ollama、LM Studio 以及 CLI 型 providerclaude-cli、codex-cli、gemini-cli等几十个条目每个条目都携带default_model与env_var提示。两点值得注意的源码细节自定义端点支持custom:前缀例如custom:https://...且校验只要求 http/https 前缀合法isValidCustomProviderUrl见 src/onboard.zig#L176-L182并不强制/v1后缀providerRequiresApiKeyForSetupsrc/onboard.zig#L189-L212会区分哪些 provider 必须填 keyOllama、LM Studio、各类 CLI provider 返回false无需 key而指向localhost/本地回环的端点也视为无需 key 的自托管场景。三、Common Defaultsonboard 写入的常见默认值原文档列出的常见默认值如下全部保留default_temperature有效默认值为0.7。这与 src/config.zig#L210 中default_temperature: f64 0.7的默认值完全一致该字段在解析时有 0.02.0 的合法区间校验src/config.zig#L1605会话运行时会将default_temperature作为初始温度src/config.zig#L425。memory.backendonboard 引导阶段选择的记忆后端。quick setup 通过resolveMemoryBackendForQuickSetupsrc/onboard.zig#L297-L301解析后端键并能区分未知后端与编译期禁用但已知的后端两类错误。memory.profile由后端选择派生。以 config.example.json 为例markdown后端对应profile: markdown_only并附带database_path、auto_save等配套字段。memory.auto_saveonboard 按后端给出的后端特定默认值例如 markdown 后端默认为true。tunnel.provider取值为none、cloudflare、ngrok、tailscale之一。这四档正是 onboard 向导 Step 5Tunnel的选项src/onboard.zig#L2591-L2601此外 config.example.json#L242-L260 还展示了custom隧道的完整子配置start_command、health_url、url_pattern可供手动扩展。agents.defaults.heartbeatonboard 正常情况下保持运行时默认值不动即every: 30m、enabled: false直到你手工编辑。这对应 src/config.zig#L255-L256 的默认heartbeat_enabled false、heartbeat_interval_minutes 30。序列化时分钟数会被渲染为every字符串大于等于 60 分钟渲染为1h之类的小时格式否则渲染为30m之类的分钟格式src/config.zig#L1167-L1173解析侧同样支持every: 30m、2h等字符串对应测试见 src/config.zig#L6637-L6667。四、Autonomy Settings自主性档位如何映射到配置字段原文档明确给出了 autonomy 的映射规则这是 onboard 配置中最值得细读的部分autonomy.level取值为supervised、full或yolo枚举定义见 src/security/policy.zig#L16别名导出在 src/config_types.zig#L13-L16。autonomy.require_approval_for_medium_risksupervised为true其余为false。autonomy.block_high_risk_commandssupervised/autonomous为truefully autonomous/yolo为false。autonomy.block_medium_risk_commandssupervised/autonomous为truefully autonomous/yolo为false。注意向导交互界面提供了4 个档位supervised/autonomous/fully_autonomous/yolo而 config 字段中的level枚举只有 3 个值二者通过 src/onboard.zig#L2612-L2646 的映射逻辑关联向导选项autonomy.levelrequire_approval_for_medium_riskblock_high_risk_commandsblock_medium_risk_commands1. supervisedsupervisedtruetruetrue2. autonomousfullfalsetruetrue3. fully_autonomousfullfalsefalsefalse4. yoloyolofalsefalsefalse源码注释点明了各档位的语义autonomous是完全行动但仍硬性阻止中/高风险命令src/onboard.zig#L2620fully_autonomous是完全行动且不硬性阻止中/高风险命令src/onboard.zig#L2627yolo则绕过所有命令级策略检查src/onboard.zig#L2634。这一映射还由单元测试固化src/onboard.zig#L4649-L4653。在 config.example.json#L226-L234 中可以看到完整默认块level: supervised、workspace_only: true、max_actions_per_hour: 20、三个安全布尔均为true。其中workspace_only与max_actions_per_hour未在 CONFIG.md 中列出属于 onboard 通常不动、留给手工调优的扩展字段。五、Channel Configuration渠道凭据与白名单当你在向导中配置渠道时渠道特有的凭据与白名单会被写入channels之下。原文档的三条规则凭据留在对应的渠道块内部例如 Telegram 的bot_token、webhook_secret只出现在channels.telegram.accounts.main内而不散落在顶层。参见 config.example.json#L42-L86 的 telegram、external、irc 三个示例块。allow_from控制谁可以与 Agent 对话telegram 示例中是[YOUR_TELEGRAM_USER_ID]精确用户 ID 白名单而 irc 与 whatsapp-web 示例中是[*]放行所有人。onboard 源码中渠道配置位于 Step 7Channels渠道凭据均写入各自渠道块内。省略的渠道块 该渠道未配置config.json 中没有出现的渠道键即视为关闭这也符合保持 config.json 精简的总体原则。六、Practical Notes四条实践要点原文档的实践建议是配置维护的关键全部保留并补充实现依据即使 config.json 省略了 API key环境变量依然生效。onboard 完成后的下一步提示正是引导你export ENV_VARsk-...src/onboard.zig#L224而每个 provider 的环境变量名由providerEnvVar查询src/onboard.zig#L327-L331例如 OpenRouter →OPENROUTER_API_KEY、Anthropic →ANTHROPIC_API_KEY。这意味着你可以安全地把凭据放在环境里、让 config.json 保持干净。未知键通常会被忽略但最好保持 config.json 精简且显式。冗余或拼写错误的键既浪费阅读成本也可能掩盖真实的配置意图从源码结构看配置解析采用宽松的字段读取方式未识别的键不会导致启动失败但这不应成为随意堆砌字段的理由。手工更换 provider 时保持agents.defaults.model.primary与所配置的 provider 条目对齐。模型路由是provider/model格式主模型必须指向一个已配置凭据/端点的 provider否则请求会落到未就绪的通道上。补充一条源码提供的运维能力如果需要把工作区引导文档重置回内置默认可以使用resetWorkspacePromptFilessrc/onboard.zig#L2964-L3031它会用embedFile的内置模板覆盖 SOUL.md、AGENTS.md、TOOLS.md、CONFIG.md、IDENTITY.md、USER.md、HEARTBEAT.md 等文件注意该操作会覆盖已有修改需谨慎使用。七、CONFIG.md 的运行时消费链路源码级补充为完整理解这份文档的价值值得梳理它在运行时被读的三条链路系统提示注入buildSystemPrompt按需加载工作区 markdown 文件并注入系统提示src/agent/prompt.zig#L286 起CONFIG.md在其中以独立 section 出现对应测试断言注入后提示包含### CONFIG.mdsrc/agent/prompt.zig#L1622-L1642。这让 Agent 在每次对话中都记得自己的运行配置。变更指纹与提示重建workspacePromptFingerprint把CONFIG.md与其余引导文件一起纳入 FNV1a-64 指纹计算文件内容变化会触发系统提示重建保证 Agent 感知到的配置永远与磁盘一致src/agent/prompt.zig#L220-L283。引导文档生命周期在非文件型 memory 后端如 API 型后端上CONFIG.md会通过 bootstrap provider 写入持久存储键名为__bootstrap.prompt.CONFIG.mdsrc/memory/root.zig#L351并参与isBootstrapFilename识别src/bootstrap/provider.zig#L74。结语CONFIG.md虽短却是理解 NullClaw 配置体系的最佳入口它以极小的篇幅勾勒了workspace、provider 凭据与端点、默认模型路由、温度与 heartbeat 默认值、自主性档位映射和渠道白名单等核心概念。结合 src/onboard.zig、src/config.zig 与 config.example.json 一起阅读你既能明白向导为什么这样写也能放心地手工调整这些字段而不破坏系统对配置的感知。若需要完整的 schema 级细节建议进一步查阅 docs/zh/configuration.md 与 docs/en/configuration.md 等配置专项文档。赞分享人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP Clients【免费下载链接】nullclawFastest, smallest, and fully autonomous AI assistant infrastructure written in Zig项目地址https://gitcode.com/gh_mirrors/nu/nullclaw点击查看免费下载相关推荐NullClaw 配置指南config.json 完整字段解析与实战配置手册NullClaw 配置指南config.json 完整字段解析与实战配置手册 NullClaw 使用与 OpenClaw 兼容的 snake_case JSO人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP ClientsAgent 沙箱多智能体语音NullClaw 配置指南从 config.json 到全自主运行NullClaw 配置指南从 config.json 到全自主运行 NullClaw 是一款使用 Zig 编写的开源 AI 助手基础设施其配置体系与 Ope人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP ClientsAgent 沙箱多智能体语音nullclaw 首次开机引导指南读懂 BOOTSTRAP.md完成 AI Agent 的出生对话nullclaw 首次开机引导指南读懂 BOOTSTRAP.md完成 AI Agent 的出生对话 本指南以 nullclaw 工作区模板 BOOTST人工智能AI Agent大模型自主智能体工具调用RAGAgent 记忆MCP ClientsAgent 沙箱多智能体语音创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考