服务器配置

🔵 平台由两个文件进行配置：config/server.yaml（核心、提供商、 日志、auth、widget）和 config/budgets.yaml（预算组和 模板绑定）。调度在 config/cron.yaml 中，变更监控在 config/monitors.yaml 中，工作流在 config/workflows/ 中。密钥在 .env 中 （机器本地），或以加密形式存放在 config/secrets.yaml 中 （参见 配置版本化）。

3.1 配置来源 — 本地文件夹或 git 仓库

整个配置树（server.yaml、agents/、web/、workflows/、 budgets.yaml、cron.yaml、monitors.yaml）从同一个根加载。默认情况下是本地 ./config；也可以改为克隆 git 仓库， 以便配置与二进制文件分开进行版本化和评审。

优先级：CLI 标志 → 环境变量 → 本地 ./config。

AGENT_OS_CONFIG_REPO=https://github.com/org/agent-config \
AGENT_OS_CONFIG_REF=v1.2.0 \
./agent-os serve

仓库被克隆到 ~/.agent-os/configs/<repo>-<ref> 的本地 分支（--config-ref），而不是 detached HEAD，以便主机可以提交和 推送；提交的 SHA 在启动时写入日志，并可在 /health 的 config 字段中看到。配置轮询器执行 merge --ff-only/rebase —— 本地提交 （配置版本）不会被覆盖。密钥可以加密形式存储在配置仓库中 （config/secrets.yaml，参见 配置版本化）；.env 和 env.overrides.yaml 仍留在仓库之外。

3.2 config/server.yaml

provider — LLM

provider:
  base_url: "https://api.deepseek.com"   # любой OpenAI-совместимый endpoint
  model: "deepseek-v4-flash"
  api_key: ""                            # опционально; предпочтительно .env
  pricing:                               # оценка стоимости инференса
    prompt_per_million: 0.14
    cached_per_million: 0.014
    completion_per_million: 0.28
  fallbacks: ["strong"]                  # цепочка failover при сбое провайдера
  circuit_breaker:                       # пропускать упавший провайдер
    failure_threshold: 5                 # подряд ошибок до размыкания (0 = выкл.)
    cooldown_secs: 30                    # пауза до пробного запроса
    half_open_max: 1                     # успешных проб для замыкания

Circuit breaker（原生）。 在连续 failure_threshold 次错误后， 提供商被标记为「open」，并在 failover 链中被跳过 —— 请求 会转到下一个提供商，而不是反复冲击已故障的提供商。经过 cooldown_secs 后， 用一个请求（half-open）试探该提供商：成功则闭合电路，错误 则再次断开。断路器的键是 model-config 名称（default、strong、……）。 该机制是核心的一部分（agent_os_core::circuit_breaker）。这里设置的是 全局默认值；具体 agent 可以通过钩子 kind: circuit_breaker 覆盖它（参见 06-hooks-routing §6.17）。由 操作员通过 Kernel::provider_breakers().reset(name) 重置。

密钥选择顺序：provider.api_key → AGENT_OS_API_KEY → DEEPSEEK_API_KEY。全部为空 → agent 以模拟响应作答。

models — 命名模型

附加模型配置：每个都会成为单独的提供商，拥有自己的 base_url / api_key / model / pricing。Agent 模板通过其 agent.yaml 中的 model: 字段选择所需的模型。上面的 provider: 是默认值（它也会 注册为 "default"）。

models:
  cheap:
    base_url: "https://api.deepseek.com"
    model: "deepseek-chat"
  strong:
    base_url: "https://api.openai.com/v1"
    model: "gpt-4o"
    api_key: ""

kernel — 调度器和会话

kernel:
  scheduler: round_robin
  concurrency_limit: 3
  time_slice_secs: 30
  live_reload: true
  session_ttl_secs: 300
  session_cleanup_interval_secs: 60
  max_output_tokens: 4096

logging — 日志和存储

logging:
  filter: "agent_os=debug"
  jsonl_dir: "logs"
  duckdb_path: "logs/events.db"
  messages_db_path: "logs/messages.db"
  messages_retention_days: 30
  state_db_path: "logs/state.db"
  temp_dir: "logs/temp"
  access_db_path: "logs/access.db"
  cron_db_path: "logs/cron.db"
  user_db_path: "logs/users.db"
  team_db_path: "logs/teams.db"
  monitor_db_path: "logs/monitors.db"
  workflow_db_path: "logs/workflows.db"
  bench_db_path: "logs/bench.db"
  side_effect_db_path: ""            # пусто = идемпотентность выключена
  outbox_db_path: ""                 # пусто = outbox/саги выключены
  dead_letter_db_path: ""            # пусто = dead-letter только в памяти
  durable_db_path: ""                # пусто = durability (durable-агенты) выключена
  pending_db_path: ""                # пусто = pending (approvals/ввод/await_event) только в памяти

teams — 命令访问

通过存在 logging.team_db_path 来启用（参见 §45「命令与访问」）。 该节选择哪些资源受团队授权管控。

teams:
  gated_tools: ["gdrive_upload", "notion_write"]   # только по гранту команды

对代理和模块化路由的访问不在此处配置：代理 — 通过 template 授权 （加上每代理的 login），路由 — 通过声明 Access::Team。

sandbox — 主机上进程的限制

对工具、脚本（shell()/exec()）和浏览器启动的进程的全局策略。 无根限制：Unix — setrlimit （CPU/AS/NPROC/NOFILE/FSIZE）+ 新会话/进程组；Windows — Job Object （内存/进程/CPU，关闭时终止）。文件系统限制（read_roots/write_roots）— 通过 Landlock（Linux）和路径检查；树级内存/CPU/pid — cgroup v2。 网络目前不受限制。 空/enabled: false = 已关闭。 每代理覆盖 — agent.yaml → sandbox:。

sandbox:
  enabled: true
  cpu_secs: 30          # лимит CPU-времени
  mem_mb: 512           # адресное пространство / память процесса
  max_procs: 64         # число процессов
  max_fds: 256          # открытых файловых дескрипторов
  max_file_mb: 64       # размер создаваемого файла (Unix RLIMIT_FSIZE)
  read_roots: []        # allowlist чтения (пусто = без ограничений); file_tool, fs_read/fs_list
  write_roots: []       # allowlist записи (пусто = без ограничений); file_tool, fs_write
  cgroup_parent: ""     # cgroup v2 для лимитов (Linux); пусто = cgroups выкл
  cpu_quota_percent: null  # доля одного ядра (cgroup cpu.max), напр. 50 = 0.5 ядра
  allow_net: true       # false = процесс в изолированном netns (Linux, без сети)
  clear_env: true       # очистить окружение
  env_allow: [PATH, LANG, HOME]   # что оставить при clear_env

后端（Linux）： 文件系统限制（read_roots/write_roots）通过 Landlock（无根，内核 ≥5.13）在 file_tool 和脚本 fs_* 中应用；内存/CPU/pid 限制 — 通过 cgroup v2（树级，包括后代），当设置了 cgroup_parent 时；网络（allow_net: false）— 通过 unshare(CLONE_NEWUSER | CLONE_NEWNET)（无路由）。在 Windows 上，资源限制由 Job Object 提供。

可观测性。 沙箱拒绝会被计数并记录日志；GET /metrics 返回 agentos_sandbox_violations_total{kind="…"}（例如 fs_read_denied、 fs_write_denied）。

cgroup v2 — 部署要求。 cgroup_parent 必须 委托给服务（无根模型）：目录 D 不含进程，启用 D/cgroup.subtree_control（库启用 +memory +pids +cpu 中可用的）， 属于服务用户，且服务本身 在 D/<child> 内启动。systemd 示例：单元上的 Delegate=yes + sandbox.cgroup_parent: /sys/fs/cgroup/<slice>/<unit>。

auth — 管理 API 和 Web 登录

auth:
  admin_token_env: ""              # имя env-переменной с токенами (опционально)
  admin_tokens:                    # карта имя → токен (или { token, templates })
    admin: "<token>"
    drom-op:
      token: "<token>"
      templates: [drom-agent]
  users:                           # web-логин: логин → пароль (или { password | password_env, templates })
    admin:
      password_env: AGENT_OS_ADMIN_PASSWORD   # пароль из env, а не из git
    drom-viewer:
      password: "<password>"
      templates: [drom-agent]
  web_user_secret_env: ""          # env с HMAC-секретом для токенов конечных пользователей

• users — /login 页面的登录：值为字符串密码或对象 { password | password_env, templates }。password_env 指定包含密码的环境变量 — 这样真实密码不会进入 git；在变量未设置之前，用户被禁用。没有 templates — 完全访问。在 /health 和模块配置中，密码始终替换为 ***。
• admin_tokens — имя → токен 的映射。名称写入访问日志（用于审计）， 令牌本身从不记录日志。值为裸令牌（完全访问）， 或对象 { token, templates }，将主体限制为列出的 模板。
• admin_token_env（可选）— 环境变量名，其值可以是 逗号分隔的列表 / ; / 换行符，每个元素为 имя=токен 或 裸令牌（名称从指纹派生）。此类令牌始终为完全访问。 没有预定义名称：要使变量 AGENT_OS_ADMIN_TOKEN 生效， 需要显式写入 admin_token_env: AGENT_OS_ADMIN_TOKEN。注意：一旦 设置了该字段，认证即被视为启用 — 如果此时变量为空， 管理 API 将关闭（401）。
• users — логин → пароль 的映射，用于 /login 页面；为管理 UI 发放 session-cookie （/sessions、/budgets）。Cookie HttpOnly，存活 12 小时，用户 名写入访问日志。值为裸密码或 { password, templates }。
• 空映射 + 空环境变量 = 认证已关闭（管理 API 开放 — 仅限开发）。
• 认证已配置，但没有任何令牌/用户被解析 → 管理 API 故障关闭（401）。

web_user_secret_env — 包含 HMAC 密钥的环境变量名，用于签名 最终用户身份令牌（POST /v1/user-ticket）。如果为空，服务器 自行生成并将密钥存储在 data/web_user_secret — 身份 默认通过 HMAC 签名。详情见 08-http-api。

管理端点接受 Authorization: Bearer <токен> 或 cookie agentos_session。

相同的来源（auth.users 和 auth.oidc）也服务于最终 用户在小组件中的登录：代理可以通过 login.required: true 要求授权（providers — OIDC，allow_users — 来自 auth.users 的登录名/密码）。参见 04-building-an-agent 和 19-widget-and-channels。

auth.oidc — 通过 Google / Yandex / Tinkoff 登录

除了密码（auth.users）之外，管理 UI 还可以通过外部 身份提供商登录（OIDC / OAuth 2.0，Authorization Code + PKCE）。角色通过 外部身份的授权授予 — subject（精确 provider:sub）、email 或 email_domain（后缀）。第一个匹配获胜；无匹配 = 登录 被拒绝（故障关闭）。

auth:
  oidc:
    base_url: ""                         # пусто = авто-вывод из запроса (Host + X-Forwarded-Proto)
    providers:
      google:
        issuer: "https://accounts.google.com"   # discovery
        client_id: "<client id>"
        client_secret_env: "GOOGLE_OIDC_CLIENT_SECRET"
      yandex:                                   # discovery нет — явные endpoints
        authorization_endpoint: "https://oauth.yandex.ru/authorize"
        token_endpoint: "https://oauth.yandex.ru/token"
        userinfo_endpoint: "https://login.yandex.ru/info?format=json"
        client_id: "<client id>"
        client_secret_env: "YANDEX_OIDC_CLIENT_SECRET"
        scopes: ["login:email", "login:info"]
        userinfo_sub_field: "id"
        userinfo_email_field: "default_email"
      tinkoff:
        issuer: "https://id.tinkoff.ru/auth/realms/tinkoff"
        client_id: "<client id>"
        client_secret_env: "TINKOFF_OIDC_CLIENT_SECRET"
    grants:
      - email_domain: "example.com"
        role: "admin"                        # полный доступ
      - email: "ops@example.com"
        templates: [drom-agent]              # оператор: только эти шаблоны

• base_url — 用于构建 redirect_uri 的公共 origin。空（默认） = 从请求推导：Host（或 X-Forwarded-Host）+ 来自 X-Forwarded-Proto 的协议（在 TLS 终止代理后 — https）。显式值 覆盖自动推导，并且必须与注册的
• 提供商 redirect_uri（对于连接器——必需）。
• 密钥（client_secret_env）——仅通过 env，绝不内联。
• Redirect URI（在提供商处注册）： {origin}/login/oidc/{provider}/callback（管理员）和 {origin}/v1/login/widget/{provider}/callback（组件）。
• 没有 client_id 的提供商会忽略。
• 这些提供商在组件中对最终用户可用 （GET /v1/login/widget/:provider）——包括用于代理模板的强制登录 login.required（§19.1）。

connectors — 以用户身份访问外部 API

代理可以以最终用户的身份在第三方服务（Google Drive、Yandex.Disk 等）中操作。 连接器复用来自 auth.oidc.providers 的 OIDC 客户端，并请求自己的 scope。令牌按用户存储在 logging.connector_db_path 中，使用 AES-256-GCM 加密（密钥来自 auth.connector_encryption_key_env 或自动密钥 data/connector_secret）。

connectors:
  gdrive:
    provider: google
    scopes: ["https://www.googleapis.com/auth/drive.file"]
  yandex_disk:
    provider: yandex
    scopes: ["cloud_api:disk.app_folder"]

工具（kind: oauth_connect / kind: connector_request）通过 tool_files 接入 agent.yaml —— 参见 05-tools-reference。连接器的 Redirect URI： {base_url}/v1/connectors/callback。

widget — 可嵌入组件

widget:
  default_model: "drom-agent"   # агент по умолчанию

唯一的服务器端设置是 default_model：当未显式指定模型时，组件所调用的代理。 组件的完整解析（嵌入、模型选择顺序、演示、视觉块）——见 §19。

proxy — HTTP 代理限制

proxy:
  allow_hosts: []   # пусто = любой публичный хост

/proxy 和 /proxy/content 在每次重定向时始终阻止私有、loopback、link-local 和 reserved 范围（包括 169.254.169.254）。 allow_hosts 额外按主机限制（精确匹配或 子域）。

inbound — 传入 webhook

inbound:
  token_env: ""   # env с bearer-токеном для POST /v1/inbound/:template (пусто = открыто, dev)

POST /v1/inbound/:template —— 外部系统同步触发代理的一次运行。 参见 08-http-api。

approval — 操作审批（human-in-the-loop）

approval:
  required_tools: ["refund", "send_email", "delete_*"]  # glob-паттерны тулов, требующих одобрения
  operator_notify:              # доставка операторских запросов в мессенджер/webhook
    - type: telegram
      chat_id: -100123456789
      token_env: TG_OPERATOR_TOKEN
    - type: webhook
      url: https://ops.example.com/approvals
  context_template: |           # необязательный MiniJinja-шаблон контекста
    📝 {{ user_request }}
    {% for m in messages %}{{ m.role }}: {{ m.content }}{% endfor %}

• required_tools —— 按工具名称全局门控，无需修改每个工具的 YAML。 逐项设置（severity / approver / timeout / 上下文）——在工具自身的 approval: 部分中。完整描述和示例——23-approvals.md。

modules — 模块和原生插件

平台是模块化的：功能（workflow、cron、频道、docs、widget、approvals 等） 和原生扩展作为模块接入——linked crate 或 DLL。

modules:
  enabled: [docs, widget, analytics]  # активировать на буте (+ requires транзитивно)
  auto_install: false                  # не ходить в сеть за артефактами на старте

• enabled —— 要激活的模块 id 列表；依赖项（requires） 会传递性地拉取，always-on 模块（kernel、web）隐式启用， 未知 id 会被忽略。为空——使用内置默认集合。
• enabled ≠ installed：列表仅表示「激活什么」；安装产物 （网络）——是单独的操作，auto_install —— 启动时补装的选项。
• 原生 DLL 单独加载——从 config/plugins.yaml；单独的 工具/钩子可以通过 kind: dll_tool / kind: dll_hook 接入。

参见 20-native-plugins 和 32-building-a-module。

3.3 config/budgets.yaml

budget_groups:
  - name: my-shared
    refill_per_sec: 50
    max_bucket: 50000
    max_total: 5000000        # null/отсутствует = без лимита
    warn_at: 0.8              # порог on_budget_threshold для группы
    per_user:                 # опционально
      refill_per_sec: 20
      max_bucket: 20000
      max_total: 500000
      warn_at: 0.8            # порог on_budget_threshold для per_user
    per_session:              # опционально
      refill_per_sec: 30
      max_bucket: 10000
      max_total: 200000

agents:
  - template: my-agent        # перекрывает budget_group / budget из agent.yaml
    group: my-shared
    budget:                   # опционально
      refill_per_sec: 10
      max_bucket: 200
      max_total: 1000

• 组在启动时立即创建（而非惰性），并在 /budgets 上可见。
• agents: 将模板（按 name）绑定到组和/或覆盖其预算。
• 来自 budgets.yaml 的覆盖优先于来自 agent.yaml 的值。
• 每次进入轮次时自上而下检查：组 → per_user → per_session。耗尽的层级通过来自 budget_messages.* 代理的消息显示。

预算字段

warn_at 可以在每一层设置（группа / per_user / per_session）， 并且钩子会为阈值被跨越的那一层调用（level = group / user / session）。

3.4 计划任务（config/cron.yaml）

Cron 按计划运行代理模板。在两个位置设置，两者 都支持热重载：

• 按代理 —— config/agents/<agent>/agent.yaml 中的 cron: 列表 （template 默认为代理自身）；
• 全局 —— config/cron.yaml，其中每个任务显式指定 template：

jobs:
  - name: morning-digest
    template: rss
    schedule: "0 0 9 * * *"      # sec min hour dom month dow (UTC)
    prompt: "Резюмируй сегодняшние новости."
    notify: [{ type: log }]

每个任务恰好指定 schedule / interval_secs / oneshot_at 之一， 并将结果投递到 notify-sink 列表（log、webhook、telegram、 vk、yandex_messenger、messages_db、agent、email、workflow）。历史记录在 logs/cron.db， 端点 GET /v1/cron。完整参考——11-cron-jobs。

3.5 变更监视器（config/monitors.yaml）

监视器是一种拉取触发器：监视外部源，仅在出现新元素时 启动代理的一次运行（与按计划独立触发的 cron 不同）。完整描述——监视器。

monitors:
  - name: news-watch
    source:
      type: rss
      url: "https://lenta.ru/rss"
    template: rss-agent
    prompt: "Кратко резюмируй эти новые статьи:\n{{items}}"
    notify: [{ type: telegram, chat_id: 123456 }]
    poll_secs: 300

监视器将游标存储在 logs/monitors.db 中：首次轮询仅「追赶」 （保存游标，不启动任何内容），之后仅在比游标更新的元素上启动。

3.6 环境变量

.env 在启动时自动加载（dotenv）。它位于 .gitignore， 模板为 .env.example。

3.7 实时重载

在 kernel.live_reload: true（默认）下，服务器监视 config/ 并 无需重启即可应用更改：

• config/agents/** — 新会话获得新指令；工具、 钩子和路由（route_files）会重新注册，并从下一次 调用起生效。已删除的 tool/hook 文件会被注销。损坏的 agent.yaml 不会拖垮其余部分：模板、工具和路由的集合保持 不变。
• config/web/** — 站点会重新渲染；新增和删除的页面 会立即生效（见 §13）。
• config/routes/**、config/hooks/**、config/workflows/**、 config/cron.yaml、config/budgets.yaml — 会重新注册；已删除的 元素会被注销（预算组的 id 会变化，活动进程 会在下次启动时重新绑定）。
• config/server.yaml — 不会即时应用；需要重启。

如果配置来自 git 仓库，在 --config-poll / AGENT_OS_CONFIG_POLL 时，同一路径会在每次新提交后应用； 未变化的 SHA 会被跳过。

3.8 HTTP 请求日志记录

每个 HTTP 请求（方法、路径、状态、持续时间、客户端 IP、user-agent、 X-User-Id、管理令牌名称）都会写入 logs/access.jsonl 和 logs/access.db （两者均可通过在相应 logging 字段中填入空字符串来禁用）。令牌的 值不会被记录 — 只会记录其名称或 invalid 标记。

3.9 ONNX 服务（security.onnx）

用于 NER / 分类 / 嵌入的本地 ONNX Runtime。需要以 onnx 特性构建 服务器。ONNX Runtime 核心不会被链接，也不会随附：它会动态加载 （load-dynamic），并在首次使用时由 runtime 块解析/下载。模型会延迟加载，并在首次使用时 下载（固定修订版本），除非 download: never / offline: true。

security:
  onnx:
    models_dir: data/models
    download: auto            # auto | eager | never
    offline: false
    allow_hosts: []           # пусто = встроенные хосты HF (+ GitHub для runtime)
    runtime:                  # динамически загружаемое ядро ONNX Runtime
      # lib_path: /opt/onnxruntime/lib/libonnxruntime.so  # явный путь (без скачивания)
      version: "1.28.0"       # должно соответствовать ort (rc.13 → 1.28)
      variant: cpu            # cpu | gpu | cuda12 | cuda13 | directml
      # base_url: https://github.com/microsoft/onnxruntime/releases/download/v1.28.0
      # sha256: "..."
    models:
      - id: langid            # используется хуком language_guard (detector: onnx)
        task: text_classification
        # templates: [ngu-agent]        # per-agent селектор (необязательно)
        source:
          hf: { repo: onnx-community/language_detection-ONNX, revision: <commit>, path: onnx/model_quantized.onnx }
        tokenizer: tokenizer.json
        config: config.json

管理端点：GET /v1/onnx/models、GET /v1/onnx/metrics、 GET /v1/onnx/runtime。

模型 langid（mini-BERT，约 25 MB int8，200 种语言）默认注册， 并由带有 detector: onnx 的 language_guard 钩子使用 （06 §6.18）。如果 服务或模型不可用，该钩子保持中立。