第29章 配置参考 | Omnigent

配置参考

Omnigent 的配置项用于控制 CLI、本地服务器、harness 以及托管沙箱。这些设置与 agent 的可移植 YAML 规范以及 REST API 相互独立。

配置作用域

作用域 / 文件 or 命令 / 用途： - Project / .omnigent/config.yaml 或 omni config set KEY=VALUE / 当前项目的默认值。项目值会覆盖用户值。 - User / ~/.omnigent/config.yaml 或 omni config set --global KEY=VALUE / 跨项目共享的默认值，以及本地服务器拥有的设置。 - Deployed server / omni server --config /path/to/config.yaml / 该部署环境下所有用户和会话的全局设置。

运行 omni config list 可查看生效的用户和项目配置。使用 omni config unset KEY 或 omni config unset --global KEY 可分别移除对应作用域中的值。

并非所有键在每个作用域中都有效。下文列出的每个设置项都标明了其作用域、类型、默认值和校验行为。

自动会话标题

设置值 / 键：session_title_instructions - 作用域：User 或部署服务器；拒绝项目级值 - 类型：字符串，最多 4,000 个字符 - 默认值：无额外指令

使用自然语言指令来控制会话标题的格式。这些要求同时适用于以下两种情况： 1. 从会话中的第一条消息生成的标题 2. 后续通过 sys_session_rename 工具进行的 agent 发起的改名

示例： omni config set --global \ 'session_title_instructions=Prefix pull request titles with the PR number and use a short snake_case name.'

此设置属于服务器，而非 agent 的可移植指令。对于本地服务器，必须使用全局作用域。在部署服务器上，请在传递给 omni server --config 的 YAML 文件中设置相同的键：

session_title_instructions: | Prefix pull request titles with the PR number. Use a short snake_case name for other work.

生成器会收到当前日期（格式为 YYYY-MM-DD）以及第一条消息。默认生成的标题限制在 100 个字符以内；超过限制的输出将被拒绝，并回退到使用第一条消息作为标题。当设置了自定义指令时，生成的标题可使用最多 200 个字符，更长的输出将被截断并添加省略号。手动指定的标题也受 200 个字符限制。

当 agent 使用 sys_session_rename 重命名会话时，其建议的标题会根据这些相同的要求进行格式化，然后才应用改名。如果格式化失败，则保留现有标题，而不是用未格式化的建议值替换。如果没有自定义指令，则直接使用 agent 的建议值。手动指定的标题永远不会被重新格式化。

该设置在本地服务器重启后生效，适用于新会话标题和 agent 改名。空值会移除额外指导。非字符串值或超过 4,000 个字符的字符串将被忽略，并使用默认的标题提示。

Web UI 基础路径

设置值 / 键：OMNIGENT_WEB_BASE_PATH 环境变量，或 omni server --base-path - 作用域：仅限服务器进程（环境变量或 CLI 参数）；不是 config.yaml 键 - 类型：URL 路径前缀——以斜杠开头，不以斜杠结尾，例如 /proxy/6767 - 默认值：未设置——服务运行在源站根路径 (/)

将服务器和 Web UI 部署在反向代理（如 code-server 的 /proxy// 或 nginx 的 location 块）下的路径前缀之后。Web UI 会在其 API、SSE、WebSocket 和资源 URL 前添加前缀，而服务器接受带或不带前缀的请求，因此前缀剥离和非重写代理都能通过该值正常工作。该参数是环境变量的简写形式，优先级高于继承的值。

空字符串和 / 被视为未设置。缺少的前导斜杠会被添加，末尾斜杠会被移除。如果值以 // 开头、包含字母、数字及 -._~/ 以外的字符、包含 ./.. 片段、或其第一段与保留的 API 命名空间或顶层 Web UI 路由冲突，则启动时将被拒绝。有关保留段位的完整列表、需配合的认证变量以及本地托管服务器如何记住前缀，请参阅“子路径服务”。

附件限制

设置值 / 键：filesystem_attachment_max_bytes, filesystem_attachment_max_files, filesystem_attachment_max_total_bytes, filesystem_attachment_denied_extensions - 作用域：服务器配置 (omni server --config) - 适用：.zip, .docx, .xlsx, .pptx, .db, .sqlite, .sqlite3 上传

ZIP 归档、Office 文档和 SQLite 数据库的上传基于文件扩展名允许，并存储为未解压状态；harness 在工作区检出之外读取本地副本（参见“归档、Office 文档和数据库附件”）。

这些格式要求使用 Claude Code (claude-native) 或 Codex (codex-native)，以及支持其传输和恢复的执行主机/运行器。上传、复制和分叉路由对它们应用以下限制：

- filesystem_attachment_max_bytes：默认 52428800 (50 MiB)，单个文件的字节数 - filesystem_attachment_max_files：默认 20，每个会话中存储的这些类型文件的数量 - filesystem_attachment_max_total_bytes：默认 209715200 (200 MiB)，每个会话中这些类型的总字节数 - filesystem_attachment_denied_extensions：默认 []，进一步限制允许列表，例如 [".zip", ".db"]

示例： filesystem_attachment_max_bytes: 26214400 # 每个文件 25 MiB filesystem_attachment_max_files: 10 filesystem_attachment_max_total_bytes: 104857600 # 每个会话 100 MiB filesystem_attachment_denied_extensions: [".zip", "db"] # 前导点可选

拒绝扩展名条目的大小写不敏感，带或不带前导点均可。非非空字符串的条目会被跳过并产生警告；如果值不是列表，则整个设置被忽略。拒绝列表只能缩小内置允许列表，且不会限制 agent 通过其他工具创建或下载的文件。

这些是基于文件名的准入和存储限制，而非内容检查：服务器不会通过字节识别文件格式、检查归档条目或检测重命名的二进制内容。图像、PDF 和文本/代码上传保留其单独的现有限制。Web 作曲家也有一个针对这些格式的固定 50 MiB 上限，因此将 filesystem_attachment_max_bytes 提高到该值以上对从 Web UI 进行的上传无效。

沙箱访问。运行器将附件副本写入执行主机上的 ~/.omnigent/attachments//（或在被覆盖时写入 $OMNIGENT_DATA_DIR/attachments/），harness 接收该绝对路径。自定义沙箱和提供程序配置必须允许运行器写入此缓存且 harness 的文件读取工具能读取它；对 workdir 的读取权限不涵盖 attachments/。如果 harness 运行在单独的命名空间，请在相同的绝对路径下暴露会话缓存。将对新增访问权限的作用域限制在所需的缓存范围，而不是整个数据目录（数据目录还包含凭据）。

请求阶段自定义策略

会收到这些附件的文件名和内容类型，文本值为空；其内容不会被作为文本扫描。

托管沙箱

Kubernetes 沙箱配置 操作系统沙箱配置 云沙箱配置

路由

智能路由配置