11.2 在脚本和 agent 里用 banz

本页讲在脚本里调用 banz 时用得到的选项，以及 agent 怎么使用 banz 的工具。

机器可读的输出

所有命令都可以加 --json，输出完整的 JSON 结果。输出不是终端时（比如通过管道交给另一个程序），默认就是 JSON。

banz session waiting --json | jq '.items[].session.session.title'

先预览、再执行

每个命令都能用的选项：

选项	作用
--json	输出 JSON
--dry-run	只打印要发出的请求，不真正执行
--yes	确认高风险的操作，不再询问，用于脚本
--timeout 2m	最多等多久，默认 30 秒
--host URL	连另一个地址上的 banz，而不是本机的
--data-dir、--config	指定 banz 的数据文件夹和配置

每个命令的帮助里写着它的风险级别（Risk: 一行）：

级别	意思
read	只读
write	写入
high-risk-write	高风险写入，比如删除，执行前要确认；脚本里加 --yes

写入类命令大多有 --command-id：不写时自动生成；重试时用同一个值，可以安全地重发，不会做两次。

banz schema 名词.动词 打印一个命令的请求、结果和选项，例如：

banz schema session.create

agent 使用 banz

banz 会把自己的工具提供给它运行的 agent，不需要你做任何配置。会话里的 agent 可以：

• 查自己在哪个项目和主题、更新会话的工作状态；
• 列出同一个项目、同一个主题里的会话，给别的会话发消息、读它们的消息、等它们回复；
• 在工作流的步骤里交回这一步的结果；
• 召回和阅读记忆、把内容交给记忆、查看这次会话用了哪些记忆；
• 记下、查找、删除设备记忆；
• 读群聊、话题和成员，在群聊里发消息；
• 查看本机有哪些 agent 程序可用。

你在 banz 之外、直接在终端里运行的 Claude Code 和 Codex，也可以用 banz 的一部分只读工具，比如召回和阅读你的记忆、查找设备记忆。

banz harness connect      # 把 banz 加到本机 claude 和 codex 的配置里
banz harness disconnect   # 移除

默认是连接的。在设置的“通用”里的“Claude Code 与 Codex”也能开关。连接时，它们在你自己的终端里干活也能用上 banz 里的记忆；不连接就用不到。

banz harness list         # 本机配好的 agent 程序：是否可用、支持什么

设置

banz 的设置可以在工作台的设置窗口里改（见 2.4 设置窗口），也可以在命令行里改：

banz config list                       # 所有设置和当前值
banz config get session.linger         # 一个设置的值、来源和可选值
banz config set session.linger 5m      # 修改
banz config reset session.linger       # 恢复默认

有的设置要重启 banz 才生效（banz host restart）。设置窗口里的“高级”列出没有归组的和标为高级的设置；所有设置都能用设置窗口的搜索找到。