附录 C：配置参考

定位：这是 config.json 与 profile 文件的完整字段参考——每个顶层配置节一张表，字段路径、类型、默认值、一句话作用、来源行号全部亲测自 octos 9c157101（crates/octos-cli/src/config.rs 共 3,790 行，crates/octos-cli/src/profiles.rs 共 7,003 行）。功能语义（沙箱怎么选后端、MCP 怎么握手、goal 三档继承怎么运作）见对应章节，本附录只回答"这个字段是什么、默认多少、在哪定义"。与 Ch9（扩展机制）交叉的 mcp_servers / sub_providers 在这里只给字段表。

C.1 配置文件位置与加载顺序

顶层 config.json 的解析顺序（crates/octos-cli/src/config.rs:1715 resolve_config_file_path）：显式 --config <FILE> 覆盖 →（默认安装下）项目本地 <cwd>/.octos/config.json → <config_home>/config.json →（默认安装下）legacy ~/.octos/config.json。无文件时写入位置回退到 config_home/config.json。

profile 文件位于 ~/.octos/profiles/<id>.json（crates/octos-cli/src/profiles.rs:5），数据目录默认 ~/.octos/profiles/{id}/data（crates/octos-cli/src/profiles.rs:164）。

C.2 顶层 Config（crates/octos-cli/src/config.rs:26）

mode 枚举定义在 crates/octos-cli/src/config.rs:14：Local（独立安装、无 tunnel、dashboard 在 /admin/）、Tenant（frpc tunnel 接入云）、Cloud（VPS 中继 + 租户管理 + 落地页）。

C.3 gateway 节（crates/octos-cli/src/config.rs:1524 GatewayConfig）

queue_mode 枚举（crates/octos-cli/src/config.rs:1499）：followup（FIFO 逐条）、collect（默认，同会话拼接）、latest（只留最新，别名 steer）、interrupt（取消当前）、speculative（慢调用并发起新 agent）。

octos serve 的默认端口是 50080（crates/octos-cli/src/config.rs:283 处文档示例）。

C.4 fallback_models[]（crates/octos-cli/src/config.rs:460 FallbackModel）

C.5 sandbox / tool_policy / snapshots

sandbox（crates/octos-agent/src/sandbox/mod.rs:37 SandboxConfig）

tool_policy（crates/octos-agent/src/tools/policy.rs:28 ToolPolicy）

tool_policy_by_provider 为同结构 map（crates/octos-cli/src/config.rs:132），键为精确 model ID（优先）或 provider 前缀。

snapshots（crates/octos-agent/src/snapshot.rs:122 SnapshotConfig）

C.6 embedding / memory / email / voice

embedding（crates/octos-cli/src/config.rs:655 EmbeddingConfig）

memory（crates/octos-cli/src/config.rs:694 MemoryConfig）

设计默认值来自 crates/octos-cli/src/config.rs:772 MemoryRefreshConfig::knobs。

email（crates/octos-cli/src/config.rs:856 EmailConfig）

voice（crates/octos-cli/src/config.rs:936 VoiceConfig）

云 TTS 密钥永不落此节：token 走 env_vars["VOLC_TTS_TOKEN"]（crates/octos-cli/src/config.rs:1040 with_cloud_token_from_env）。

C.7 hooks 与 approval_policy

hooks[]（crates/octos-agent/src/hooks.rs:77 HookConfig）

event 可取（crates/octos-agent/src/hooks.rs:58 as_str）：user_prompt_submit、before_tool_call、after_tool_call、before_llm_call、after_llm_call、on_resume、on_turn_end、before_spawn_verify、on_spawn_verify、on_spawn_complete、on_spawn_failure。

approval_policy（crates/octos-cli/src/config.rs:545 ApprovalPolicyConfig）

校验逻辑在 crates/octos-cli/src/config.rs:587 validate：非空 tools、require_approval == true、非空 approvers、expires_in_secs > 0，否则 fail fast。

C.8 自适应路由与运维节

adaptive_routing（crates/octos-cli/src/config.rs:1085 AdaptiveRoutingConfig）

monitor（crates/octos-cli/src/config.rs:1284 MonitorConfig，api feature）

dashboard_auth（crates/octos-cli/src/otp.rs:46 DashboardAuthConfig）

dashboard_auth.smtp 整体可省（crates/octos-cli/src/otp.rs:56），缺省时 OTP 走控制台输出。

credential_pool（crates/octos-cli/src/config.rs:415 CredentialPoolConfig）

appui（crates/octos-cli/src/config.rs:339 AppUiConfig）与 plugins（crates/octos-cli/src/config.rs:315 PluginsConfig）

C.9 mcp_servers[] 专节（crates/octos-agent/src/mcp.rs:53 McpServerConfig）

字段表见下；协议行为（握手、DNS 防回环、OAuth 流程）详见 Ch9，此处不重复。

不可配置的硬限制（常量）：握手超时 30s（crates/octos-agent/src/mcp.rs:43）、单次 tools/call 60s（crates/octos-agent/src/mcp.rs:45）、工具输入 schema 嵌套 ≤10 层（crates/octos-agent/src/mcp.rs:47）、schema 序列化 ≤64KB（crates/octos-agent/src/mcp.rs:49）。

C.10 sub_providers[] 专节（crates/octos-cli/src/config.rs:618 SubProviderConfig）

spawn 子 agent 可引用的模型车道。保留键：goal_verifier（#1935）：存在时该 lane 成为独立的 goal 完成校验模型，否则回退到旧行为（用评分会话自己的 provider 校验）。与 Ch9 的分工：那边讲 spawn 工具如何消费这些车道，这里只给字段。

C.11 validators（声明式校验器，workspace policy 层）

validators 不在 config.json 里——它是工作区策略文件 .octos-workspace.toml（crates/octos-agent/src/workspace_policy.rs:13 WORKSPACE_POLICY_FILE）中 validation 节的子键。顶层策略结构 WorkspacePolicy 在 crates/octos-agent/src/workspace_policy.rs:22；validation 节（crates/octos-agent/src/workspace_policy.rs:115 ValidationPolicy）：

每个 Validator（crates/octos-agent/src/workspace_policy.rs:143）：

spec 变体（crates/octos-agent/src/workspace_policy.rs:301 ValidatorSpec，serde tag kind，snake_case）：

• command：cmd（必填）、args（默认 []）：子进程命令，走 shell 安全层（crates/octos-agent/src/workspace_policy.rs:306）
• tool_call：tool（必填）、args（默认 {}）：调用注册的 agent 工具（crates/octos-agent/src/workspace_policy.rs:313）
• file_exists：path（必填）、min_bytes（默认 null）：断言文件存在/最小字节数（crates/octos-agent/src/workspace_policy.rs:318）
• http_probe：url_template（必填）、expected_status（默认 200）、expected_contains（默认 null）：HTTP 探测，默认 5s 超时（crates/octos-agent/src/workspace_policy.rs:325）
• ominix_voice_exists：name_arg（必填）：查 ominix-api 已注册自定义音色（crates/octos-agent/src/workspace_policy.rs:336）
• audio_non_silent：glob（默认 ""）、min_ratio（默认 0.3）、source（默认 glob 模式）、extension（默认 null）：音频非静音比例（crates/octos-agent/src/workspace_policy.rs:344）
• per_file_non_silent：整文件逐一非静音校验，require_at_least 计数（crates/octos-agent/src/workspace_policy.rs:368 附近）
• 魔数断言 MagicByteKind：mp3/wav/png/jpeg/pdf/mp4/webm/pptx（crates/octos-agent/src/workspace_policy.rs:469）

运行时常量：命令类默认超时 30s（crates/octos-agent/src/validators.rs:55 DEFAULT_COMMAND_TIMEOUT_MS）、HTTP 探测默认 5s（crates/octos-agent/src/validators.rs:60 DEFAULT_HTTP_PROBE_TIMEOUT_MS）、证据文件在 <workspace_root>/.octos/validator-evidence/（crates/octos-agent/src/validators.rs:53）、单条证据 ≤512KB（crates/octos-agent/src/validators.rs:62 MAX_EVIDENCE_BYTES）。

C.12 profile 体系简表

profile 文件 ~/.octos/profiles/<id>.json 的 config.llm 是一等结构化 LLM 选择契约，不是顶层 config.json 那种 provider/model 扁平键。三层结构：

config.llm（crates/octos-cli/src/profiles.rs:814 LlmProfileConfig）

config.llm.primary / 每个 fallback（crates/octos-cli/src/profiles.rs:824 LlmModelSelectionConfig，#[serde(deny_unknown_fields)]）

config.llm.primary.route（crates/octos-cli/src/profiles.rs:881 LlmRouteConfig）

三档继承（crates/octos-cli/src/profiles.rs:2403 resolve_effective_profile）：子 profile 带 parent_id 时，父的 LLM 契约整体覆盖继承（ec.llm = pc.llm），review/search/deep_crawl/apps/email/tool_policy 等结构节则仅当子级为空时继承；无 parent 则原样返回。这是 goal 三档（operator 默认 → 队列 → worker 覆盖）中 profile 侧的机制，完整三档语义见 Ch15。

最小可用 profile JSON 示例（密钥只出现环境变量名，无任何密钥值）：

{
  "id": "writer",
  "display_name": "Writer",
  "config": {
    "llm": {
      "primary": {
        "family_id": "deepseek",
        "model_id": "deepseek-v4-pro",
        "route": {
          "route_id": "wisemodel",
          "base_url": "https://api.wisemodel.cn/v1",
          "api_key_env": "WISEMODEL_API_KEY"
        },
        "temperature": 0.3,
        "context_window": 131072
      },
      "fallbacks": [
        {
          "family_id": "moonshot",
          "model_id": "kimi-k2.5",
          "route": { "api_key_env": "MOONSHOT_API_KEY" },
          "strong": true
        }
      ]
    },
    "memory": { "max_inject_tokens": 4000 }
  }
}

C.13 完整 config.json 示例（JSONC 注释）

{
  // 迁移版本，当前 1
  "version": 1,
  // 主 LLM(扁平键；serve 多租户请用 profile 的 config.llm)
  "provider": "anthropic",
  "model": "claude-sonnet-4",
  "api_key_env": "ANTHROPIC_API_KEY",
  "env_vars": {},
  "context_window": 200000,          // #2142 覆盖目录/探测
  // failover 链
  "fallback_models": [
    { "provider": "openai", "model": "gpt-4o", "strong": true, "cost_per_m": 2.5 }
  ],
  // 会话与工具
  "max_iterations": 50,
  "format_after_edit": true,         // #1774 编辑后自动格式化
  "context_filter": [],
  "tool_policy": { "deny": [], "allow": [] },
  "sandbox": {
    "enabled": true,
    "mode": "auto",
    "allow_network": false,
    "workspace_write": true
  },
  "snapshots": { "enabled": false, "keep_last": 20 },
  // MCP server(见 C.9;协议细节见 Ch9)
  "mcp_servers": [
    {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {},
      "concurrency_class": "safe"
    }
  ],
  // 子 agent 车道(见 C.10;goal_verifier 为保留键)
  "sub_providers": [
    { "key": "cheap", "provider": "openai", "model": "gpt-4o-mini", "api_key_env": "OPENAI_API_KEY" }
  ],
  // 生命周期 hooks(C.7)
  "hooks": [
    { "event": "after_tool_call", "command": ["cargo", "check"], "timeout_ms": 5000, "tool_filter": ["edit_file"], "path_filter": [] }
  ],
  // gateway(C.3)
  "gateway": {
    "channels": [{ "type": "cli", "allowed_senders": [], "settings": {} }],
    "max_history": 50,
    "queue_mode": "collect",
    "llm_timeout_secs": 120
  },
  // 自适应路由(C.8)
  "adaptive_routing": { "enabled": false, "mode": "off" },
  // 记忆与 embedding(C.6)
  "memory": { "max_inject_tokens": 4000, "refresh": { "enabled": true } },
  "embedding": { "provider": "openai", "model": "text-embedding-3-small", "api_key_env": "OPENAI_API_KEY" },
  // 运维(C.8)
  "mode": "local",
  "allow_admin_shell": false,
  "appui": { "allowed_origins": [], "sessions_in_cwd": true },
  "plugins": { "require_signed": false },
  "cli": { "serve": { "port": 50080 } }
}

C.14 版本演化说明

本附录数据基线为 octos main 9c157101（docs(guide): document mcp_servers stdio fields, env sanitization, timeouts, #2211/#2212）。相对早期基线的主要演化：

• typed LLM schema（3a567a4c / #2166）：LlmModelSelectionConfig 新增 temperature / top_p / reasoning_effort / context_window（#2142 拆自 #2127），顶层 Config 同步投影出 model_temperature / model_top_p / model_reasoning_effort（crates/octos-cli/src/config.rs:56-65），与 gateway.llm_temperature / gateway.llm_sampling_params（#2172）构成显式优先级链。
• mcp_servers：profile 级 [[mcp_servers]] 在 OLP #29 S2b 前不会注册工具（crates/octos-cli/src/profiles.rs:198 注释）；stdio 字段、env 清洗与超时在 #2211/#2212 文档化。
• sub_providers 保留键 goal_verifier（#1935）：缺省时 goal 完成校验回退评分会话自身 provider（旧行为）。
• hooks schema：现行为 hooks[] + event + command（argv）+ timeout_ms（默认 5000）+ tool_filter: string[]，另有较新的 path_filter 与 requires_bin。
• queue_mode：steer 更名 latest（crates/octos-cli/src/config.rs:1507-1512，serde 别名保留兼容）。
• snapshots（#1768）、approval_policy、appui.sessions_in_cwd、plugins.require_signed、cli 节均为后续新增；sandbox.write_allow_globs（#1976）与 tool_policy.bash_file_writes（#28b）是近期收紧项。

旧版附录中的数字与字段表一律作废，以本表为准。