运行 zerocode

本地设置

在与守护进程相同的机器上，无需额外配置：

zerocode

zerocode 会自动查找守护进程的本地端点：在 Unix 上为 <data_dir>/data/daemon.sock，在 Windows 上为 \\.\pipe\zeroclaw-<hash>。如果守护进程未运行，zerocode 会生成一个临时的守护进程。

会话工作目录

在本地连接中，新建的 Chat 和 Code 会话会在你启动 zerocode 时所在的目录中启动，因此文件和 Shell 工具会针对该项目进行操作。重新启动的本地会话也是如此。如果 zerocode 无法确定该目录，或其路径不是有效的 UTF-8，则不会创建会话，并会显示原因，而不会悄悄地在其他位置启动。

通过远程（WSS）连接时，你启动 zerocode 所在的目录位于另一台机器上，因此不会被发送。新建的远程 Chat 会话会使用所选智能体在守护进程上配置的工作区。

守护进程会解析请求的根目录，依据该智能体的策略进行检查，并回报会话实际使用的目录。无论会话从何处启动，智能体的身份与人格文件仍从其已配置的工作区中读取。

远程 (WSS) Code 总是会先询问。新建或重启的远程 Code 会话会在创建会话之前打开守护进程端的目录选择器，因此其根目录始终是你在守护进程文件系统上选定的目录。该选择器浏览的是守护进程所在机器，而不是你的本地机器，并且没有可回退的默认目录。

在 Code 面板中，/change-directory 会打开目录选择器，并在所选目录中启动新会话。它在本地和 WSS 两种连接下都可用：本地连接时，选择器浏览的是本机；通过 WSS 连接时，选择器浏览的是守护进程所在机器的文件系统。现有会话不会被移动，它仍保留在自己保存的根目录中，你可以随时切换回去。取消选择器，或守护进程拒绝所选目录时，都会返回该现有会话且保持不变，并提示原因。

恢复的 Code 会话会保留创建时的工作目录，即使之后你的启动目录或智能体配置的工作区发生了变化。Chat 则不同：仍在守护进程上运行的 Chat 会话在 zerocode 重新连接时会保留其目录，但守护进程不会保存 Chat 会话的目录。守护进程需要重建的 Chat 会话（例如守护进程重启之后）会从所选智能体当前的工作区开始。

切换会话

在 Chat 和 Code 窗格中，您可以在不重新启动 zerocode 的情况下加载或切换现有会话：

• 切换会话 打开会话列表（默认按键组合：Ctrl+S；可在 keymap 中重新绑定）。
• 使用列表导航键移动选择项（默认：Up/Down）。
• Enter 切换到高亮的会话。
• 新建会话会打开与侧边栏 [+] 相同的添加代理选择器，并为所选代理添加一个会话，同时保持当前聚焦的会话处于跟踪状态（默认快捷键：Ctrl+N；可重新绑定）。

点击会话行的主体区域可使其获得焦点；点击其右侧边缘的 ✕ 则会直接关闭该特定会话，而无需先将其聚焦。使用会话标题栏中的 [+] 可添加同级会话，使用 [-] 可关闭活动窗格中已聚焦的会话。关闭正在运行的会话时，会安全地停止其当前工作，同时保留持久化的历史记录。

切换到已有的 Code 会话时，会在其保存的根目录中恢复该会话；而 New session 则会重新开始：本地会话位于启动 zerocode 时所在的目录，远程 Chat 会话位于所选代理的工作区，远程 Code 会话位于你在守护进程端选择器中挑选的目录。这两种操作都不会改变已在运行的会话的根目录；如果需要将 Code 会话放到其他位置，请使用 /change-directory。

应用内帮助覆盖层会显示这些操作的实时按键绑定。

Chat/Code 会话和基于 ACP 的会话使用不同的存储。如果你直接使用 ACP 协议，在需要回放对话记录时使用 session/load，在只需要恢复服务端会话状态时使用 session/resume。有关协议级细节，请参阅 ACP documentation。

终端文本输入

zerocode 以原始模式作为终端 UI 运行。它接收终端按键和粘贴事件，而不是原生平台文本字段事件。因此在 macOS 上，系统文本替换仅在你的终端在 zerocode 接收输入之前将其展开时才会生效。

Composer 编辑

Chat 和 Code 编辑器支持这些默认设置。“Primary”在 macOS 上指 Command，在其他系统上指 Control；当终端能够传递字面的 Control 别名时，这些别名同样有效。

撤销历史属于当前草稿，最多保留 100 个编辑组。连续输入（包括空格）一次撤销。停顿两秒、光标或选区移动、鼠标点击或拖动，或其他编辑命令都会结束当前输入组。粘贴的文本、补全、剪切、清除和换行各自构成一次独立编辑。在选区上输入会开始新的编辑组；撤销会恢复被选中的文本及选区。光标移动不产生编辑。撤销后进行新的文本编辑会丢弃重做历史。撤销和重做会恢复文本、光标和选区，但绝不会添加或移除附件。发送、切换会话或加载排队消息进行编辑时，会开始全新的历史记录。

选择快捷键作用于当前聚焦的输入框，而非队列侧边栏。复制选中的输入内容不会取消正在运行的回合，也不会退出；当没有输入选择时，Control+C 保留其取消/退出行为。对话框和记录浏览保留各自的快捷键。使用 /attach 浏览文件；可配置的 browse files 操作默认没有快捷键，因为 Primary+A 现在用于选择文本。帮助浮层显示当前配置的快捷键绑定。

终端或操作系统快捷键可能会在 zerocode 收到 Command、Control 或剪贴板事件之前将其拦截。剪贴板复制使用终端的 OSC 52 支持;括号粘贴仍可正常使用。

CLI flags

终端状态

zerocode 会使用两种转义序列约定，自动将最紧急的 Chat 或 Code 轮次状态发布到终端：

• OSC 2 用于设置简短、易读的标签页标题，例如 ⏳ my-agent — working 或 ⚠ my-agent — awaiting approval。
• OSC 9;4 可报告进度已清除、不确定进度或警告进度，无需其他程序解析标题文本。

两个序列都从 zeroclaw-api 中与内容无关的生命周期契约推导出空闲、工作中、阻塞和已完成的语义；Zerocode 仅将思考中、回复中或当前工具等本地化细节用于显示。侧边栏中的每个活动会话都是候选项，无论是否获得焦点：阻塞优先于工作中，工作中优先于空闲，已命名的会话在平局时胜出。

这是终端元数据，与特定的工作区管理器无关。兼容的终端和多路复用器可能会显示、保留或使用它；不支持这些序列的软件会忽略它们。负载仅包含所选代理的别名以及有界的状态或工具名称。它从不包含提示词、工具参数、工具输出或响应文本。

如果与守护进程的连接断开，zerocode 会立即清除进度，并显示中性的 ✓ zerocode 标题，而不是保留缓存的工作中或阻塞状态。会话状态仍可用于重新连接，只有在守护进程重新连接后，才会再次投影实时会话状态。

在正常退出和受支持的终止信号下，zerocode 会清除进度显示；若终端支持标题栈，则还会恢复终端标题。对于不支持标题栈的终端，它会写入中性的 zerocode 作为后备标题。与所有终端程序一样，它无法在不可捕获的 SIGKILL 或机器突然关机后进行清理。之后终端或 shell 更新标题，或关闭标签页，都会清除这些过时的显示内容。