
ZeroClaw zerocode Config 面板完全指南本地 UI 配置、键位修饰符规范与环境变量覆盖【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw导读zerocode 是 ZeroClaw 项目中运行在终端里的客户端TUI它的Config 面板是配置一个正在运行的 ZeroClaw 实例的首选入口每个设置都有类型化控件、校验逻辑与内联说明且大多数设置无需重启守护进程即可实时生效。本文围绕 docs/book/src/zerocode/config.md 展开结合 apps/zerocode/src/config/mod.rs 等源码完整讲解 Config 面板的工作方式、zerocode-config.toml中 TodoWrite 追踪器与侧边栏的配置写法、键位修饰符的规范拼写以及ZEROCODE_*环境变量覆盖的机制。读完你可以在任何 zerocode 会话里熟练完成设置修改、脚本化配置与旧版本升级。Config 面板是什么zerocode 的Config面板是配置正在运行的 ZeroClaw 的方式。它不是一个简单的键值编辑器而是一套结构化的配置界面具备以下四个核心特征类型化控件typed control每个设置都有与之匹配的输入控件——布尔开关、下拉选择、数值输入等从根本上杜绝了把数字填进布尔字段这类低级错误。校验validation控件在值到达守护进程之前就拒绝非法输入因此一次手滑的拼写错误不可能把配置留在无法加载的状态。内联说明inline explanation每个设置都自带一段就地说明告诉你这个字段到底做什么无需再去交叉翻阅配置参考手册。实时生效live apply大多数设置在下一帧就生效无需重启守护进程。打开方式很简单从任意 zerocode 会话进入 Config 面板即可所有编辑都应在面板中完成而不是手改配置文件。设置依然会持久化到你的配置文件中文档对相关字段的描述可以看作该控件最终会写入什么的权威说明而不是让你打开文件去手工编辑的指令。手工编辑仅作为无头headless主机与脚本化预置scripted provisioning场景下的后备手段。为什么用面板而不是手改文件优势说明校验Validation控件在值到达守护进程前就拒绝畸形值拼写错误不会让配置文件变得无法加载可发现性Discoverability每个设置都带内联描述无需查配置参考手册就能知道字段含义实时应用Live apply大多数设置在下一帧生效无需重启注册表驱动的列表Registry-backed listsProvider、channel、model、theme 等选择项来自后端注册表你看到的选项与当前构建实际支持的能力完全一致其中注册表驱动的列表是关键设计配置面板里出现的选项不是写死的字符串而是来自后端注册表这保证了 UI 选项与实际可用的 provider/channel/model/theme 永远同步。键位修饰符的规范拼写键位绑定使用规范化的修饰符名称canonical modifier names这是持久化值的标准形式control字面意义的 Control 键primarymacOS 上为 Command其他平台上为 Controlsuper字面意义的 Super/Command 键。例如controlc、primaryr、altshiftup都是可移植的持久化值。注意primary与control的区分——primaryr在 macOS 上表示⌘r在 Linux/Windows 上表示Ctrlr这让同一份配置文件在不同平台上有符合平台习惯的键位。旧版ctrl...的自动迁移历史上遗留的ctrl...写法会在配置加载时被自动迁移一次并重写为对应的规范拼写。从 apps/zerocode/src/config/mod.rs 的migrate_legacy_ctrl_bindings实现可以看到具体的拆分规则——它在加载阶段重写整个[keybindings]表的字符串值当按键是c、g、k、n、s、f1时ctrlX会被改写为controlX其他按键如a、d、e、h、p、r、u、v、w、x、enter、up等会被改写为primaryX。对应的测试 legacy_ctrl_migration_uses_the_frozen_key_split 完整覆盖了这两组按键的映射。这套拆分逻辑的动机是controlc等组合在所有平台上语义一致如中断而大多数ctrl字母组合在 macOS 上习惯用 Command因此前者保留字面control后者统一转成平台自适应的primary。另外迁移只在配置加载时发生一次load_persisted检测到ctrl后会回写规范化后的文档且canonical_keybindings_reload_idempotently测试保证了已规范化的配置重复加载不会产生二次改写是幂等的。本地 UI 设置zerocode-config.toml有一部分设置描述的是zerocode 自身如何绘制它的面板而不是守护进程的行为。这些设置存放在 zerocode 自己的文件config-dir/zerocode-config.toml中并从 zerocode 的Config面板进行编辑。该文件名的常量定义见 config/mod.rsFILE_NAME zerocode-config.toml。TodoWrite 追踪器TodoWrite 追踪器就是其中之一。它是一个纯展示层面的组件守护进程只是发出计划更新plan updates在 ACPAgent Client Protocol协议上由客户端完全控制渲染格式因此它归 zerocode 所有[todotracker] enabled true # master switch; when false the tracker never renders enabled_at_start false # visible at launch, before the first plan arrives location right # bottom, left, or right width 32 # side-panel target column width (left/right) max_height 5 # bottom-strip maximum height in rows各字段说明enabled总开关为false时追踪器永不渲染enabled_at_start是否在启动时首个 plan 到达前就可见location渲染位置枚举为bottom、left、right对应源码 TodoTrackerLocation 中的Bottom/Left/Right默认Rightwidth侧边面板的目标列宽用于 left/right 位置默认值 32见 default_todotracker_widthmax_height底部条带的最大行高用于 bottom 位置默认值 5见 default_todotracker_max_height。校验规则width与max_height必须大于 0。源码中的validate()会在每个权威边界执行——Config 面板保存前会先校验会话边界解析生效后post-env-override的配置时也会再次校验因此文件或环境变量中显式的0会可见地失败而不会被悄悄归一化为 1。生效时机TodoWrite 的值会在每个会话边界重新读取因此你在 Config 面板中的修改会在下一次启动、重启或切换会话时生效无需重启 zerocode。Shell 级 Agent 侧边栏同文件还存放 shell 级 agent 侧边栏配置。默认节会被显式序列化这样环境变量覆盖就有了可定位的 schema 节点[sidebar] visible true # show the agent/session sidebar at launch width 24 # target width in terminal columnsvisible启动时是否显示 agent/session 侧边栏默认truewidth目标宽度终端列数默认 24见 default_sidebar_width。按CtrlB即可显示或隐藏侧边栏。Quickstart快速开始仍可从键盘模式栏keyboard mode bar访问同时也作为侧边栏启动器出现即使在窄终端宽度下也可见。从侧边栏选择一个已有 agent 会启动一个新的 Chat 或 Code 会话而不会替换该面板已经追踪的其他会话。环境变量覆盖Environment overrides任何字段都可以通过ZEROCODE_前缀的环境变量为单次运行覆盖。拼写规则是前缀 小写的配置路径路径中的.写成__ZEROCODE_todotracker__enabledfalse zerocode ZEROCODE_todotracker__locationbottom zerocode ZEROCODE_sidebar__visiblefalse zerocode三条命令分别演示了禁用 TodoWrite 追踪器、把追踪器位置改为底部、启动时隐藏侧边栏。对应的常量在 config/mod.rs 中定义ENV_PREFIX ZEROCODE_、ENV_SEP __。关键语义——进程瞬态这些覆盖只影响当前运行的实例永远不会写回zerocode-config.toml。在 Config 面板中保存一个无关字段也不会把环境变量注入的值烘烤bake进文件。源码通过双视图模型实现这一保证见 ensure_and_load 与 load_persisted 与 load_persistedensure_and_load磁盘值叠加ZEROCODE_*环境覆盖后得到的生效视图运行时消费方会话、渲染读它load_persisted磁盘上的原始配置不做任何环境覆盖。任何编辑并保存的操作Config 面板必须以它为基础否则保存一个字段就会把另一个字段的 env 注入值写进文件。环境变量的值解析由set_prop完成它通过检查字段现有值的 TOML 类型来把字符串解析成正确类型字符串→字符串、布尔→布尔、整数→整数、浮点→浮点、数组→数组因此你写ZEROCODE_todotracker__enabledfalse时不需要关心底层字段类型。测试 canonical_env_spelling_overrides_tracker_field 与 env_overrides_do_not_reach_the_persisted_view 分别验证了env 覆盖胜出与env 不进入持久化视图两条契约。从守护进程持有的[todotracker]升级在[todotracker]从守护进程配置中移出之前它是守护进程config.toml的一个节。如果你在那里设置过请按以下步骤迁移打开守护进程config.toml记下[todotracker]的值将同样的块写入config-dir/zerocode-config.toml如上所示或者通过Config → Todo tracker设置从守护进程config.toml中删除[todotracker]节。关于旧环境变量已有的ZEROCLAW_todotracker__*环境变量在升级前不需要删除——这五个被识别的字段enabled、enabled_at_start、location、width、max_height会被守护进程接受并忽略因此之前可以工作的部署仍能启动。但它们已不再有任何效果请将它们迁移到上面的ZEROCODE_拼写。源码级原理配置加载分层与键位体系配置加载分层从 config/mod.rs 的模块文档可以看到 zerocode 本地配置的分层模型defaults - file (zerocode-config.toml) - ZEROCODE_* envZerocodeConfig结构体config/mod.rs建模了完整配置节说明locale界面语言默认endefault_localetheme主题含name与按 agent 覆盖的agent_overrideconnectionWSS 连接配置uri、TLS、relay 等sidebar侧边栏可见性与宽度keybindings稀疏的键位覆盖表键为tag.varianttodotrackerTodoWrite 追踪器展示配置几个值得注意的容错设计都有对应测试未知主题名回退配置里写了不存在的主题名例如新版构建写入的、或拼写错误时resolve_theme会回退到继承 shell 的terminal主题而不是让 TUI 崩溃测试 resolve_unknown_theme_falls_back_to_terminal坏节不影响其他节一个损坏的[keybindings]或[sidebar]只会让该节回退默认值不会清空主题等无关配置测试bad_keybindings_do_not_blank_theme、bad_sidebar_does_not_blank_theme未建模的节原样保留配置文件中当前结构体未建模的节会被原样携带部分写入永远不会误伤它们load_document与persist_*系列函数均基于整个 TOML 文档做读-改-写。键位预设与冲突校验键位体系的实现位于 apps/zerocode/src/config/keybindings.rs。系统内置了四个命名预设KEY_PRESETSdefault完整的编译期默认键位vim在保留默认方向键与 Tab 的基础上为移动类动作追加h/j/k/l、g/G等 vim 风格键emacs追加primaryp上、controln下等 emacs 风格移动键arrows_only移动动作只保留方向键与 Tab。每个预设都会先以全部默认键位为基底再叠加自己的重绑定因此任何预设都覆盖所有可重绑定动作测试 every_preset_covers_every_action 保证这一点。键位冲突由build_override_table在解析时严格校验同一动作内重复的键、同一 tag 下两个动作声明了同一个键含wire 上不同但 dispatch 时是同一个键的归一化冲突如?与Shift?都会被拒绝并给出明确错误见 build_override_table。修饰符的底层渲染修饰符的规范拼写由 apps/zerocode/src/keymap/chord.rs 中的Chord类型实现。规范化修饰符 token 注册表MOD_TOKENS是control、alt、shift、super四个 tokenwire()与from_str都遍历同一张注册表因此渲染与解析两个方向永不漂移。primary在wire()中被渲染为字面primary前缀而在事件匹配时modifiers_for_event被解析为 macOS 上的 Super⌘与非 macOS 上的 Control——这就是一份配置平台自适应的实现基础。小结zerocode 的 Config 面板把配置正在运行的 ZeroClaw从手工编辑配置文件升级为结构化的、带校验的、可实时生效的交互流程而配置的持久化仍然落在清晰可读的zerocode-config.toml上。实际使用时记住三条主线日常修改走面板类型化控件 校验 内联说明 实时生效只有无头主机和脚本预置场景才需要手工编辑文件脚本化覆盖用环境变量ZEROCODE_ 小写路径 .改__进程瞬态、绝不落盘升级注意键位与 todotrackerctrl...会自动迁移为control/primary规范拼写[todotracker]已从守护进程配置迁至 zerocode 自己的文件旧ZEROCLAW_todotracker__*变量被接受但不再生效。如需深入底层建议继续阅读 apps/zerocode/src/config/mod.rs配置分层、校验与持久化、apps/zerocode/src/config/keybindings.rs键位预设与 apps/zerocode/src/keymap/chord.rs修饰符语义。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考