CyberStrikeAI/docs/zh-CN/configuration.md

配置参考

CyberStrikeAI 的主配置文件是 config.yaml。大多数配置也可以在 Web 的“系统设置”中修改，保存后再应用。生产环境中，建议把敏感值放在受控配置系统中，并限制 config.yaml 的文件权限。

基础配置

version: "v1.6.51"
server:
  host: 0.0.0.0
  port: 8080
  tls_enabled: true
  tls_auto_self_sign: true
auth:
  password: "change-me"
  session_duration_hours: 12
log:
  level: info
  output: stdout

• version：前端展示版本。
• server.host/port：Web 服务监听地址和端口。
• server.tls_*：HTTPS 配置。生产环境建议使用 tls_cert_path 和 tls_key_path。
• auth.password：Web 登录密码，必须改为强密码。
• auth.session_duration_hours：登录会话有效期。
• log.output：可以是 stdout、stderr 或文件路径。

模型配置

openai:
  provider: openai
  base_url: https://api.openai.com/v1
  api_key: sk-...
  model: gpt-4.1
  max_total_tokens: 120000
  reasoning:
    mode: on
    effort: high
    allow_client_reasoning: true
    profile: openai_compat

• provider：openai 表示 OpenAI 兼容接口；claude 会桥接到 Anthropic Claude Messages API。
• base_url/api_key/model：主模型配置。
• max_total_tokens：上下文压缩、攻击链构建、多代理摘要等共用的总预算。
• reasoning：控制推理扩展字段。不同网关支持差异较大，异常时先尝试 mode: off。

Agent

agent:
  max_iterations: 12000
  tool_timeout_minutes: 60
  shell_no_output_timeout_seconds: 1200
  workspace_root_dir: ""
  system_prompt_path: ""

• max_iterations：单代理、多代理主执行器和子代理的默认迭代上限。
• tool_timeout_minutes：单次工具最长运行时间。
• shell_no_output_timeout_seconds：Shell 长时间无输出时终止。
• workspace_root_dir：会话工作区根目录，建议不要设置到系统 /tmp。
• system_prompt_path：单代理系统提示词覆盖文件。

HITL

hitl:
  default_reviewer: audit_agent
  retention_days: 90
  tool_whitelist: [read_file, list_dir, glob, grep, tool_search]
  audit_model:
    provider: ""
    base_url: ""
    api_key: ""
    model: ""

• default_reviewer：human 或 audit_agent。
• tool_whitelist：全局免审批工具列表，会与会话白名单合并。
• audit_model：审计 Agent 独立模型；留空复用主模型。
• audit_agent_prompt / audit_agent_prompt_review_edit：可覆盖默认审批策略。

更多策略见 人机协同最佳实践。

多代理

multi_agent:
  enabled: true
  robot_default_agent_mode: eino_single
  batch_use_multi_agent: false
  eino_skills:
    disable: false
    filesystem_tools: true
    skill_tool_name: skill

支持模式：

• eino_single：Eino 单代理。
• deep：DeepAgent 风格多代理。
• plan_execute：规划、执行、重规划。
• supervisor：主管代理转交子代理。

agents_dir 指向 Markdown 子代理目录。单个代理可在 front matter 中设置 tools、bind_role、max_iterations。

工具与 MCP

security:
  tools_dir: tools
  tool_description_mode: full
mcp:
  enabled: false
  host: 0.0.0.0
  port: 8081
  auth_header: "X-MCP-Token"
  auth_header_value: ""
external_mcp:
  servers: {}

• security.tools_dir：内置工具 YAML 目录。
• tool_description_mode：short 更省 token，full 更完整。
• mcp.enabled：是否启动独立 HTTP MCP 服务。
• mcp.auth_header_value：外部调用 MCP 时的共享密钥，生产环境必须设置。
• external_mcp.servers：外部 MCP 联邦配置。

工具 YAML 规则见 tools/README.md。

知识库

knowledge:
  enabled: false
  base_path: knowledge_base
  embedding:
    provider: openai
    model: text-embedding-v4
    base_url: ""
    api_key: ""
  retrieval:
    top_k: 5
    similarity_threshold: 0.4
  indexing:
    chunk_size: 512
    chunk_overlap: 50
    batch_size: 10

启用后会注册知识库检索工具，并开放管理接口。详细说明见 知识库。

数据库

database:
  path: data/conversations.db
  knowledge_db_path: data/knowledge.db

默认使用 SQLite。knowledge_db_path 为空时可复用会话数据库；独立文件更便于迁移知识库。

审计与监控

audit:
  enabled: true
  retention_days: 15
  max_detail_bytes: 8192
monitor:
  retention_days: 90

• audit 记录平台操作，不记录对话正文和每次工具调用正文。
• monitor 管理工具执行记录保留时间。

C2、WebShell、项目

c2:
  enabled: true
project:
  enabled: true
  fact_index_max_runes: 65000

• c2.enabled：关闭后不启动 C2 监听器，也不注册 C2 MCP 工具。
• WebShell 连接配置存 SQLite，没有单独的主配置开关。
• project 控制跨对话事实黑板注入预算。

机器人

robots 支持个人微信 iLink、企业微信、钉钉、飞书、Telegram、Slack、Discord、QQ。详细配置步骤见 机器人使用说明。

配置修改建议

• 先在测试环境验证模型、MCP、知识库和高风险工具。
• 改动 tools_dir、roles_dir、skills_dir、agents_dir 后，检查 Web 页面是否能列出对应资源。
• 生产环境避免开启不需要的 C2、WebShell、终端和外部 MCP。
• 修改敏感配置后，检查审计页面是否有异常登录或配置变更记录。

配置应用机制

配置不是所有字段都同等“热更新”。/api/config/apply 会做一组协调动作：更新模型配置、工具描述模式、重新注册部分 MCP 工具、初始化或更新知识库、重启机器人连接、按配置启停 C2。这个逻辑在 internal/handler/config.go 中由 ConfigHandler 协调。

实务判断：

配置段	应用后通常立即生效	需要额外动作
openai	新请求使用新模型配置	旧的流式请求不会被强制切换
agent.max_iterations	新 Agent 任务生效	已运行任务按启动时状态继续
security.tool_description_mode	工具重新暴露时生效	模型已有上下文不会回滚
hitl.tool_whitelist	新工具调用审批判断生效	已挂起审批不自动重判
knowledge.enabled	会尝试初始化/更新组件	启用后仍需扫描和索引
knowledge.embedding	检索器/索引器配置更新	已有向量通常需要重建索引
robots	会触发连接重启	平台回调配置仍需在平台侧正确
c2.enabled	会协调 C2 runtime	已暴露端口和会话要人工确认
server.port/tls	通常需要重启进程	监听地址不是普通热更新

配置优先级和派生关系

几个字段有“留空复用”的关系：

• vision.api_key/base_url/provider 留空时复用 openai。
• hitl.audit_model 留空时复用 openai。
• knowledge.embedding.base_url/api_key 留空时复用主模型或 embedding 默认配置。
• knowledge.retrieval.rerank.base_url/api_key 留空时复用 embedding/openai。
• database.knowledge_db_path 留空时可以复用主会话数据库，但独立文件更利于备份。

这类配置排障时不要只看子配置段，也要看它会回落到哪个上级配置。

参数取值建议

参数	保守值	激进值	判断依据
agent.tool_timeout_minutes	10-30	60+	扫描工具是否常跑长任务
shell_no_output_timeout_seconds	300-600	1200+	工具是否长时间静默
knowledge.indexing.batch_size	5-10	20+	embedding 服务批量限制
knowledge.indexing.rate_limit_delay_ms	300-800	0-100	服务商 RPM 和 429 情况
retrieval.top_k	3-5	8-12	内容质量和上下文预算
similarity_threshold	0.35-0.45	0.5+	召回优先还是精度优先
audit.retention_days	15-30	90+	合规要求和磁盘空间
monitor.retention_days	30-90	180+	是否需要长周期复盘

变更前后验证模板

修改配置前记录：

变更目的：
涉及配置段：
预期影响：
回滚方式：
验证接口：

修改后验证：

curl -k https://127.0.0.1:8080/api/auth/validate \
  -H "Authorization: Bearer <token>"

再按配置类型验证模型、工具、知识库、C2 或机器人。不要只看 Web 保存成功提示。

源码锚点

• 配置结构：internal/config/config.go
• 环境变量展开：internal/config/envexpand.go
• Web 配置接口：internal/handler/config.go
• 路由注册：internal/app/app.go
• C2 配置协调：internal/app/c2_lifecycle.go