配置 Agent¶

主机安装使用 /etc/obs-agent/config.toml。安装器会生成配置文件；修改前先备份，修改后校验并重启服务。文件包含接入凭据，请保留 root:obs-agent 所有权及 0640 权限，不要将完整文件放入公开工单。

按功能修改配置¶

config_version = 1

[beak]
url = "https://beak.example.com"
agent_id = "replace-with-agent-id"
api_key = "replace-with-agent-api-key"

[llm]
# model = "auto"
# request_timeout = "5m"
# max_tokens = 0

[runtime]
working_dir = "/var/lib/obs-agent/work"
# http_allowed_domains = ["example.com", "api.example.com"]

[profile]
cache_dir = "/var/lib/obs-agent/profile-cache"

[logging]
level = "info"
# format = "text"

[update]
base_url = "https://releases.example.com/obs-agent"
# auto_enabled = true

[tools.browser]
# enabled = true

[tools.web_search]
# enabled = true

安装器生成配置文件，未设置的字段使用环境变量或默认值。示例中的注释供修改配置时参考，取消注释后才成为固定配置。

update.socket_path 未设置时，Agent 使用 update.state_path 所在目录下的 update.sock。这是运行时计算的路径，不需要填写占位文字。

运行时间与工具时间上限¶

8 小时上限不会延长 2 小时的运行期限。子 Agent 继承父任务的取消信号；wait_for 请求超过父任务剩余时间时会被拒绝。因此，这组默认值有效，但默认运行无法用满 8 小时。确需长任务时，应显式调整 runtime.max_run_duration，并保留与任务相符的子 Agent 和等待上限。

达到软时间预算时，Agent 等待已经开始的 LLM 请求（包括流式输出和压缩请求）或工具执行结束，不因该预算中断它们。有效最终答案正常交付；需要继续工作时，不启动新工具，最多再请求一次仅总结已有结果的回答，失败则返回可继续的 checkpoint。因此实际耗时可以超过配置值。上下文无法容纳总结或配置敏感信息只能由结构化结果展示时，直接返回 checkpoint。

仅启用时间限制时，每次 LLM 请求（包括重试）末尾追加临时 user 预算提示，不写入会话历史。提示只包含总时限、已运行时间和剩余时间，不包含工具调用数、LLM 调用数或 token 用量。调用次数和累计 token 只作内部统计，不再触发停止。关闭时间限制后不追加预算提示。

在 obscli 已连接的会话中，使用以下命令管理每轮时限：

设置会持久化，影响当前轮和后续轮；每轮重新计时，不累计整个会话的运行时间。已进入收尾的轮次不会恢复调查。运行中的子任务同步父时限变化，但保留自身更短的独立上限。API 为 GET/PUT /api/v1/sessions/:id/max-run-duration，PUT 请求体为 {"duration":"+5m"}。仅有写权限的会话参与者可修改。返回 applied 才表示当前连接的 Agent 已确认；pending、offline、unsupported 均不能当作已生效。

人工审批等待计入预算，到点结束等待，未执行的工具不会运行；晚到的批准不能恢复已终止的操作。运行中延长或缩短会重新计算审批等待期限。浏览器控制审批仍有独立的 30 分钟有效期；延长运行预算不会延长它。人工取消、单次 LLM 请求超时以及工具自身超时仍独立生效。

例如在已有 [runtime] 段中设置 max_run_duration = "4h"，可将预算改为四小时；修改后按下文校验并重启。主机和容器默认值均为两小时，容器使用 AGENT_MAX_RUN_DURATION=4h 覆盖。

布尔值写为 true 或 false，数字不加引号，列表使用数组，时长保留单位，例如 "5m"。未知字段和未知表会被忽略，包括旧 max_llm_calls、max_run_tokens；已知字段仍校验类型和值，语法错误和不支持的配置版本仍会被拒绝。环境变量中的旧调用/token 上限及 AGENT_MAX_TOOL_CALL_ITERATIONS 别名也不再读取。

确认覆盖顺序¶

主机安装的同一配置项按 TOML、已知环境变量、内置默认值 的顺序选择。字段存在就覆盖环境变量，包括 ""、false 和 0。如果该字段不允许该值，Agent 会报错，不会退回其他来源。

默认读取 /etc/obs-agent/config.toml。文件不存在时，回退已发布版本使用的 agent.env，不会合并两份文件。升级会将旧 agent.env 迁移为 config.toml 并保留备份；已有 config.toml 的设置和用户注释继续保留。

Linux 安装器为支持 TOML 的版本生成显式使用 --config /etc/obs-agent/config.toml 的服务，升级启动预检也读取同一文件。主服务不加载兼容 agent.env；旧 updater 仍使用该生成文件。

删除或注释字段后，才允许环境变量或默认值补充。config_version = 1 表示配置结构版本，与 Agent 发布版本无关；不支持的版本会被拒绝。

Agent 自助配置只修改允许修改的项，保留用户注释、空行和其他字段。手工编辑与 Agent 修改发生冲突时，Agent 会拒绝过期修改，需要重新读取后再操作。

校验、同步升级兼容文件并重启¶

sudo cp -p /etc/obs-agent/config.toml /etc/obs-agent/config.toml.bak
sudo vi /etc/obs-agent/config.toml
sudo obs-agent --config-tool agent-export \
  --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent
sudo systemctl status obs-agent

校验失败时不要重启。转换命令只将已知配置导出为旧 updater 可读取的兼容文件。不要手工修改生成的 agent.env；Agent 自助修改会同步这个文件。

需要指定其他配置文件时使用 obs-agent --config /path/to/config.toml。该选项不能与旧的 --env-file 同时使用。

如果服务无法启动，恢复备份并重新生成兼容文件：

sudo cp -p /etc/obs-agent/config.toml.bak /etc/obs-agent/config.toml
sudo obs-agent --config-tool agent-export \
  --input /etc/obs-agent/config.toml --output /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

从旧配置升级¶

主机首次升级到支持 TOML 的版本时，安装器自动转换 agent.env，校验后再切换，无需手工转换或填写字段映射。已知的有效配置会保留，即使其值恰好等于默认值；旧格式中的空值按原有“未设置”含义处理。

无法识别的变量不会进入 TOML。安装器只报告变量名，原文件保存在备份中，请按原用途检查这些变量。Agent 不提供通用环境变量分组。

旧 updater 仍可按原命令触发升级，无需先自行更新。升级继续受闲时保护；迁移或新版启动失败时恢复旧程序、配置和服务。已经确认不支持闲时协议的历史版本，其首次过渡可能中断工作；升级后的版本使用闲时保护。

配置容器 Agent¶

容器安装只通过环境变量配置，不读取或生成 config.toml，也不支持 Agent 的 --config 或 --env-file 文件参数。请使用安装页面提供的 Docker、Compose 或 Kubernetes 环境变量配置。

Docker 的 --env-file 参数仍可使用：它由 Docker 将文件内容注入容器环境变量，不是让 Agent 读取配置文件。具体操作见容器安装手册。

升级兼容性¶

LocalProvider 不再解析或转发旧 agent_max_llm_calls / agent_max_tool_call_iterations 设置。

已发布安装协议仍接收并转发旧限制字段，以兼容旧版 Agent 和安装器；新版 Agent 不再读取这些字段，也不会执行对应的次数或 token 限制。

BREAKING CHANGE：新版 Agent 不再执行累计调用次数和 token 上限。部署前确认成本控制不依赖这些旧字段。先升级 Beak，再按现有安装/自动升级流程升级 Agent；旧 Agent 可继续连接和聊天，但不会应用新会话时限。运行时通过可选 session_run_duration=v1 能力声明区分版本。回滚旧 Agent 会恢复其旧限制行为，忽略会话时限覆盖。会话设置保留，重新升级后可恢复；回滚 Beak 不删除新增的可空 run_duration 列。安装器和 updater 的调用契约不变。