完整配置手册

这份手册面向“准备长期运行 CountBot”的场景，重点解释配置存在哪里、每一层配置怎么生效，以及它们和技能、团队、定时任务、外部编码工具之间的联动关系。

配置总览

当前配置主要分成几类：

Provider 与模型
会话与人格
工作空间与安全
渠道与账号
外部编码工具
技能系统
智能体团队
定时任务
远程访问认证

配置存储与生效方式

主配置

系统主配置通过 settings API 持久化到数据库，再由后端加载为统一配置对象。

常用接口：

方法	路径	说明
`GET`	`/api/settings`	获取完整配置
`PUT`	`/api/settings`	保存配置
`GET`	`/api/settings/providers`	获取 Provider 元数据
`POST`	`/api/settings/test-connection`	测试模型连接
`GET`	`/api/settings/security/dangerous-patterns`	查看危险命令规则

工作空间配置

工作空间相关能力既受主配置影响，也依赖工作空间目录中的实际文件：

workspace/skills/
workspace/.skills_config.json
workspace/memory/
workspace/temp/

Provider 与模型配置

Provider 配置负责什么

每个 Provider 至少需要关心：

enabled
api_key
api_base

它决定某个模型提供商是否可用，以及请求该发到哪里。

全局模型配置负责什么

全局模型配置决定默认运行时参数，例如：

provider
model
temperature
max_tokens
max_iterations

这些值会被 Web 聊天、渠道消息处理和部分工作流执行路径共同读取。

测试连接的推荐顺序

先保存 Provider 的 api_key
如有必要再改 api_base
选择一个目标模型
调用 /api/settings/test-connection
测试通过后再进行真实对话

会话自定义配置

会话层支持对全局配置做局部覆盖。

当前会话可覆盖什么

model
persona

会话配置接口

方法	路径	说明
`GET`	`/api/chat/sessions/{session_id}/config`	获取会话自定义配置
`PUT`	`/api/chat/sessions/{session_id}/config`	保存会话自定义配置
`DELETE`	`/api/chat/sessions/{session_id}/config`	清空会话自定义配置

生效优先级

普通会话运行时，模型配置优先级为：

会话自定义配置
全局 Provider 配置
Provider 默认元数据

这意味着同一个 CountBot 实例里，不同会话可以临时跑不同模型，而不影响系统默认值。

人格与对话配置

人格相关配置决定聊天助手的自我介绍、称呼方式和历史长度控制。

常见字段：

ai_name
user_name
personality
custom_personality
max_history_messages

`max_history_messages` 的实际影响

影响每次对话带多少历史消息
值越大，上下文越完整，但 token 成本越高
过长对话会触发记忆系统做摘要沉淀

工作空间配置

工作空间路径影响哪些能力

文件工具默认根目录
Shell 工具默认工作目录
技能目录位置
记忆文件位置
截图、临时文件输出路径

什么时候需要重启

和工作空间根目录强绑定的组件通常在启动时初始化，所以修改工作空间路径后，建议重启应用，让技能、记忆和文件工具都重新绑定新目录。

安全配置

安全配置主要控制命令执行边界和审计能力。

常见字段：

dangerous_commands_blocked
custom_deny_patterns
command_whitelist_enabled
custom_allow_patterns
audit_log_enabled
command_timeout
subagent_timeout
max_output_length
restrict_to_workspace

最重要的两个开关

`dangerous_commands_blocked`

启用后，后端会拦截明显危险的命令模式，例如强制删除、格式化磁盘、关机重启等。

`restrict_to_workspace`

启用后，文件与命令执行会尽量被限制在工作空间内。它适合更严格的部署环境，但变更后通常需要重启才能完全生效。

渠道与账号配置

CountBot 的渠道配置是账号级设计，不是“整个渠道一个总开关”。

账号层的关键字段

enabled
display_name
account_id
allow_from
routing_mode
external_coding_profile

为什么是账号级

因为你往往需要：

同一渠道挂多个机器人
不同团队绑定不同默认路由
生产和测试走不同默认编码工具

渠道 API

方法	路径	说明
`GET`	`/api/channels/list`	获取渠道配置摘要
`GET`	`/api/channels/status`	获取运行状态
`POST`	`/api/channels/test`	测试连通性
`POST`	`/api/channels/update`	保存并重载渠道配置
`GET`	`/api/channels/{channel}/config`	获取单个渠道配置

详细配置样例见渠道配置。

外部编码工具配置

外部编码工具是渠道和聊天路由的重要组成部分。

每个 profile 常见字段

名称
启动命令
参数
工作目录
环境变量
会话模式
是否启用

配置接口

方法	路径	说明
`GET`	`/api/settings/external-coding-tools`	获取配置
`PUT`	`/api/settings/external-coding-tools`	保存配置
`POST`	`/api/settings/external-coding-tools/check`	检查 profile 是否可运行

和渠道默认路由的关系

渠道账号会保存：

routing_mode
external_coding_profile

运行逻辑：

routing_mode=ai：普通消息先进 CountBot 主 Agent
routing_mode=direct：普通消息直接转发给外部编码工具

如果选择 direct 却没有配置有效的 external_coding_profile，渠道配置不会通过校验。

会话模式说明

当前外部编码工具会话模式支持：

stateless
history
native

实现细节：

claude 的 native 支持最稳定
其他工具即使设为 native，也可能在运行时回退到 history

详细见外部编码工具。

技能系统配置

技能目录

当前技能统一放在：

workspace/skills/

启用状态文件

当前技能启用状态保存在：

workspace/.skills_config.json

示例：

{
  "disabled_skills": ["news"]
}

当前内置技能

技能	用途
`agent-browser`	浏览器自动化
`agent-team-manager`	团队管理
`baidu-search`	搜索增强
`cron-manager`	定时任务管理
`email`	邮件收发
`image-analysis`	图片分析
`image-gen`	图片生成
`map`	地图与路线
`news`	新闻聚合
`skill-creator`	技能生成与评估
`terminal-session`	终端会话辅助
`weather`	天气查询
`web-design`	页面生成与部署

技能配置 API

方法	路径	说明
`GET`	`/api/skills`	获取技能列表
`POST`	`/api/skills/reload`	重载技能
`POST`	`/api/skills/{name}/toggle`	启用或禁用技能
`GET`	`/api/skills/{name}/config/schema`	获取配置 schema
`GET`	`/api/skills/{name}/config`	获取当前配置
`PUT`	`/api/skills/{name}/config`	保存配置
`GET`	`/api/skills/{name}/config/status`	查看配置状态
`POST`	`/api/skills/{name}/config/fix`	自动修复配置
`GET`	`/api/skills/{name}/config/help`	获取配置帮助

技能配置状态值

当前后端会返回这些状态：

no_schema
not_configured
invalid_format
missing_fields
valid

哪些技能常见需要额外配置

技能	常见配置文件
`baidu-search`	`workspace/skills/baidu-search/scripts/config.json`
`email`	`workspace/skills/email/scripts/config.json`
`image-analysis`	`workspace/skills/image-analysis/scripts/config.json`
`image-gen`	`workspace/skills/image-gen/scripts/config.json`
`map`	`workspace/skills/map/scripts/config.json`
`web-design`	`workspace/skills/web-design/scripts/config.json`

其余技能多数开箱即用，或依赖本地 CLI 环境而不是 JSON 配置。

详细见技能系统。

智能体团队配置

团队配置由两部分组成：

团队定义
团队专属模型配置

团队 API

方法	路径	说明
`GET`	`/api/agent-teams/`	获取团队列表
`POST`	`/api/agent-teams/`	创建团队
`GET`	`/api/agent-teams/{team_id}`	获取团队详情
`PUT`	`/api/agent-teams/{team_id}`	更新团队
`DELETE`	`/api/agent-teams/{team_id}`	删除团队
`GET`	`/api/agent-teams/{team_id}/config`	获取团队模型配置
`PUT`	`/api/agent-teams/{team_id}/config`	保存团队模型配置
`DELETE`	`/api/agent-teams/{team_id}/config`	清空团队模型配置

团队模式

pipeline
graph
council

预定义团队工作流的模型优先级

当通过 workflow_run(team_name=...) 执行预定义团队时：

团队专属模型配置
会话模型覆盖
全局模型配置
Provider 默认元数据

团队管理技能

当前已经内置 agent-team-manager，适合在聊天中完成：

团队创建与删除
模板建队
成员增删改
团队模型配置查看、设置、重置

详细见智能体团队和 Agent Team Manager。

定时任务配置

定时任务配置不只是“Cron 表达式 + 一句话”，还包括投递、会话和重试策略。

常见字段

name
schedule
message
enabled
channel
account_id
chat_id
deliver_response
max_retries
retry_delay
delete_on_success

定时任务 API

方法	路径	说明
`GET`	`/api/cron/jobs`	获取任务列表
`POST`	`/api/cron/jobs`	创建任务
`GET`	`/api/cron/jobs/{job_id}`	获取任务详情
`PUT`	`/api/cron/jobs/{job_id}`	更新任务
`DELETE`	`/api/cron/jobs/{job_id}`	删除任务
`POST`	`/api/cron/jobs/{job_id}/run`	立即执行
`POST`	`/api/cron/jobs/batch`	批量创建
`POST`	`/api/cron/jobs/batch-delete`	批量删除
`GET`	`/api/cron/jobs/{job_id}/messages`	获取任务消息
`POST`	`/api/cron/jobs/{job_id}/session/cleanup`	清理任务会话
`POST`	`/api/cron/jobs/{job_id}/session/reset`	重置任务会话
`POST`	`/api/cron/validate`	校验 Cron 表达式

`cron-manager` 的配置联动

cron-manager 现在会读取当前聊天环境变量：

COUNTBOT_CHANNEL
COUNTBOT_CHAT_ID
COUNTBOT_ACCOUNT_ID

所以在 IM 聊天里创建任务时，能自动补齐当前渠道上下文。

详细见定时任务。

远程访问认证

远程访问认证用于保护 Web 界面和 API，不影响已有渠道机器人继续收发消息。

常用认证接口

方法	路径	说明
`GET`	`/api/auth/status`	获取认证状态
`POST`	`/api/auth/setup`	首次设置密码
`POST`	`/api/auth/login`	登录
`POST`	`/api/auth/logout`	登出
`POST`	`/api/auth/change-password`	修改密码

部署建议

外网暴露服务时应启用认证
结合反向代理、主机防火墙和数据库文件权限一起治理
如果允许远程访问，建议同步审查工作空间权限和危险命令策略

常用验证清单

模型配置验证

GET /api/settings 看 Provider 和模型是否保存成功
POST /api/settings/test-connection 验证模型连通性
新建一个会话做一次真实对话

渠道配置验证

GET /api/channels/status 看是否已运行
给目标渠道发消息，确认会话路由正确
如涉及 direct 路由，再验证外部编码工具 profile

技能配置验证

GET /api/skills 看技能是否加载
GET /api/skills/{name}/config/status 看状态是否为 valid
如状态异常，查看 config/help 或使用 config/fix

团队配置验证

GET /api/agent-teams/ 查看团队列表
检查团队成员、模式和团队模型配置
用 /team 或 workflow_run 实测一次工作流

定时任务验证

POST /api/cron/validate 验证表达式
创建任务后检查 next_run
必要时手动调用 /run 验证执行链路

配置总览​

配置存储与生效方式​

主配置​

工作空间配置​

Provider 与模型配置​

Provider 配置负责什么​

全局模型配置负责什么​

测试连接的推荐顺序​

会话自定义配置​

当前会话可覆盖什么​

会话配置接口​

生效优先级​

人格与对话配置​

max_history_messages 的实际影响​

工作空间配置​

工作空间路径影响哪些能力​

什么时候需要重启​

安全配置​

最重要的两个开关​

dangerous_commands_blocked​

restrict_to_workspace​

渠道与账号配置​

账号层的关键字段​

为什么是账号级​

渠道 API​

外部编码工具配置​

每个 profile 常见字段​

配置接口​

和渠道默认路由的关系​

会话模式说明​

技能系统配置​

技能目录​

启用状态文件​

当前内置技能​

技能配置 API​

技能配置状态值​

哪些技能常见需要额外配置​

智能体团队配置​

团队 API​

团队模式​

预定义团队工作流的模型优先级​

团队管理技能​

定时任务配置​

常见字段​

定时任务 API​

cron-manager 的配置联动​

远程访问认证​

常用认证接口​

部署建议​

常用验证清单​

模型配置验证​

渠道配置验证​

技能配置验证​

团队配置验证​

定时任务验证​

推荐联调顺序​

相关文档​

配置总览

配置存储与生效方式

主配置

工作空间配置

Provider 与模型配置

Provider 配置负责什么

全局模型配置负责什么

测试连接的推荐顺序

会话自定义配置

当前会话可覆盖什么

会话配置接口

生效优先级

人格与对话配置

`max_history_messages` 的实际影响

工作空间配置

工作空间路径影响哪些能力

什么时候需要重启

安全配置

最重要的两个开关

`dangerous_commands_blocked`

`restrict_to_workspace`

渠道与账号配置

账号层的关键字段

为什么是账号级

渠道 API

外部编码工具配置

每个 profile 常见字段

配置接口

和渠道默认路由的关系

会话模式说明

技能系统配置

技能目录

启用状态文件

当前内置技能

技能配置 API

技能配置状态值

哪些技能常见需要额外配置

智能体团队配置

团队 API

团队模式

预定义团队工作流的模型优先级

团队管理技能

定时任务配置

常见字段

定时任务 API

`cron-manager` 的配置联动

远程访问认证

常用认证接口

部署建议

常用验证清单

模型配置验证

渠道配置验证

技能配置验证

团队配置验证

定时任务验证

推荐联调顺序

相关文档