TPCLAW

Appearance

智能体配置 ​

智能体配置分为两个层级：

配置层级文件用途
全局默认配置config.yaml心跳、会话、压缩、媒体等默认值
智能体定义data/agents/*.json具体智能体的规则链、模型、工具配置

全局默认配置 ​

在 config.yaml 中配置智能体默认值：

yaml
agents:
  defaults:
    # 默认智能体 ID
    default_id: "main"

    # 心跳配置
    heartbeat:
      interval: "30m"           # 心跳间隔，0 表示关闭
      prompt: ""                # 自定义提示词，为空使用默认值
      active_hours:             # 激活时间段
        start: "09:00"
        end: "22:00"
      target: ""                # 目标通道，为空使用默认通道
      load_history: false       # 是否加载历史消息

    # 会话配置
    session:
      enabled: true
      storage_path: "sessions"  # 存储目录
      max_messages: 100         # 最大消息数量
      default_scope: "per_peer" # 作用域: per_peer, per_channel, global
      tool_call:
        save_tool_calls: true           # 保存工具调用记录
        keep_tool_calls_count: 5        # 保留最近工具调用数量
        max_tool_result_size: 2000      # 工具结果最大字符数

    # 压缩配置
    compaction:
      mode: "safeguard"         # safeguard | auto | off
      strategy: "summary"      # summary | sliding_window | hybrid
      keep_recent_count: 10     # 保留最近消息数
      target_tokens: 0          # 固定阈值（0 表示不使用）
      target_tokens_percent: 70 # 基于模型上下文的百分比（优先级高于 target_tokens）
      memory_flush: true        # 压缩时刷新内存

    # 工具安全策略（默认关闭）
    toolSecurity:
      enable: false
      mode: "deny"              # deny（黑名单）或 allow（白名单）
      denyTools: ""             # 拦截的工具名称（逗号分隔，支持 * 通配符）
      allowTools: ""            # 允许的工具名称（逗号分隔，支持 * 通配符）
      deniedTypes: ""           # 拦截的工具类型: builtin, mcp, rulechain, subagent
      cmdDenyExtra: ""          # bash 工具额外命令黑名单（逗号分隔）
      allowPaths: ""            # 文件路径白名单（逗号分隔）
      denyPaths: ""             # 文件路径黑名单（逗号分隔），优先级高于 allowPaths

    # 技能目录
    global_skills_dir: "skills"

    # 媒体存储
    media:
      enable: true
      storage_path: "media"
      max_file_size: 52428800   # 50MB

  # 单独智能体配置（覆盖默认值）
  list:
    - id: "main"
      default: true
      model: "gpt-4"
    - id: "agent01"
      heartbeat:
        interval: "1h"

配置项说明 ​

配置项说明
heartbeat.interval心跳间隔，触发智能体主动检查任务
heartbeat.active_hours激活时间段，支持跨天（如 22:00-06:00）
session.default_scope会话作用域：per_peer(按用户)、per_channel(按群)、global(全局)
compaction.modesafeguard(智能防护)、auto(全自动)、off(关闭)
compaction.strategy压缩策略：summary(LLM 摘要，默认)、sliding_window(滑动窗口，不需要 LLM)、hybrid(混合)
toolSecurity.enable是否启用工具安全拦截，默认 false
toolSecurity.mode拦截模式：deny(黑名单，命中则拦截) 或 allow(白名单，不在列表则拦截)

会话作用域 ​

作用域说明
per_peer按用户隔离，每个用户独立会话
per_channel按群组隔离，群内共享会话
global全局共享，所有用户同一会话

压缩模式 ​

模式说明
safeguard智能防护模式，在上下文接近限制时自动压缩
auto全自动模式，更激进的压缩策略
off关闭自动压缩，需手动使用 /compact 命令

压缩策略 ​

策略说明
summaryLLM 摘要压缩（默认），使用 LLM 对历史消息生成摘要，保留语义信息
sliding_window滑动窗口压缩，直接截断旧消息，不需要 LLM，适合低成本场景
hybrid混合策略，对旧消息使用摘要压缩，最近消息保持原样

工具安全策略 ​

完整说明

工具拦截、文件路径与跨目录访问控制的完整说明见 工具安全与文件访问控制，本节仅列出与智能体配置相关的部分。

通过 toolSecurity 配置控制智能体可使用的工具范围：

yaml
agents:
  defaults:
    toolSecurity:
      enable: true
      mode: "deny"
      denyTools: "bash,edit"           # 拦截 bash 和 edit 工具
      deniedTypes: "mcp"               # 拦截所有 MCP 工具
      cmdDenyExtra: "rm,sudo"          # bash 工具额外禁止 rm 和 sudo
      denyPaths: "/etc,/var"           # 禁止访问 /etc 和 /var 目录
yaml
# 白名单模式示例
agents:
  defaults:
    toolSecurity:
      enable: true
      mode: "allow"
      allowTools: "read,skill"         # 只允许 read 和 skill 工具
      allowPaths: "/data/workspace"    # 只允许访问工作空间目录
配置项说明
enable是否启用，默认 false
modedeny（黑名单）或 allow（白名单）
denyTools黑名单模式下拦截的工具名称，逗号分隔，支持 * 通配符（如 bash*）
allowTools白名单模式下允许的工具名称，逗号分隔，支持 * 通配符
deniedTypes拦截的工具类型：builtin、mcp、rulechain、subagent
cmdDenyExtrabash 工具额外命令黑名单，在工具自身安全检查之上追加
allowPaths文件路径白名单（read/write/edit 工具），为空不限制
denyPaths文件路径黑名单，优先级高于 allowPaths

智能体定义文件 ​

智能体以规则链 JSON 格式存储在 data/agents/ 目录：

data/agents/
├── main.json        # 主智能体
├── agent01.json     # 子智能体1
├── agent02.json     # 子智能体2
└── agent03.json     # 子智能体3

文件结构 ​

json
{
  "ruleChain": {
    "id": "main",
    "name": "智能体名称",
    "additionalInfo": {
      "category": "agents",
      "description": "智能体描述",
      "icon": "🤖"
    }
  },
  "metadata": {
    "firstNodeIndex": 0,
    "nodes": [...],
    "connections": [...]
  }
}

智能体节点配置 ​

智能体核心是 ai/agent 类型节点：

json
{
  "id": "node_main",
  "type": "ai/agent",
  "name": "TeamClaw",
  "configuration": {
    "url": "${global.models.providers.default.base_url}",
    "key": "${global.models.providers.default.api_key}",
    "model": "${global.models.providers.default.model}",
    "systemPrompt": "...",
    "maxStep": 100,
    "maxToolOutputLength": 50000,
    "params": {...},
    "tools": [...]
  }
}

节点配置项 ​

配置项类型说明
urlstringLLM API 地址，支持 ${global.xxx} 变量
keystringAPI Key，支持变量引用
modelstring模型名称
systemPromptstring系统提示词
maxStepint最大迭代步数，默认 50
maxToolOutputLengthint工具输出最大长度，默认 50000
paramsobject模型参数
toolsarray工具列表

模型参数 ​

json
{
  "params": {
    "temperature": 0.7,
    "topP": 0.9,
    "maxTokens": 4096,
    "frequencyPenalty": 0.5,
    "presencePenalty": 0.5,
    "stop": ["END"],
    "responseFormat": "text",
    "keepThink": false
  }
}
参数范围说明
temperature0.0-2.0采样温度，越高越随机
topP0.0-1.0核采样参数
maxTokensint最大输出长度
frequencyPenalty0.0-1.0频率惩罚，防止重复
presencePenalty0.0-1.0存在惩罚，鼓励新话题
responseFormatstring输出格式：text、json_object

系统提示词 ​

基本用法 ​

json
{
  "systemPrompt": "你是一个智能助手，帮助用户解决问题。"
}

引用模板文件 ​

使用 ${include()} 引用工作空间中的模板文件：

json
{
  "systemPrompt": "${include(global.root_dir+'/workspace/IDENTITY.md')}\n\n---\n\n${include(global.root_dir+'/workspace/AGENTS.md')}"
}

条件引用 ​

使用 ${fileExists()} 判断文件是否存在：

json
{
  "systemPrompt": "${fileExists(global.root_dir+'/workspace/BOOTSTRAP.md') ? include(global.root_dir+'/workspace/BOOTSTRAP.md') + '\\n\\n---\\n\\n' : ''}${include(global.root_dir+'/workspace/IDENTITY.md')}"
}

内置变量 ​

变量说明
${global.root_dir}数据根目录
${global.models.providers.xxx}模型配置
${ruleChain.id}当前规则链 ID
${now()}当前时间

工具配置 ​

内置工具 (builtin) ​

json
{
  "tools": [
    {
      "type": "builtin",
      "name": "read",
      "description": "读取文件内容",
      "config": {
        "maxReadLines": 2000,
        "workDir": "${global.root_dir}/workspace"
      }
    },
    {
      "type": "builtin",
      "name": "write",
      "config": {
        "workDir": "${global.root_dir}/workspace"
      }
    },
    {
      "type": "builtin",
      "name": "edit",
      "config": {
        "workDir": "${global.root_dir}/workspace"
      }
    },
    {
      "type": "builtin",
      "name": "bash",
      "config": {
        "timeout": 60,
        "workDir": "${global.root_dir}/workspace"
      }
    },
    {
      "type": "builtin",
      "name": "skill",
      "config": {
        "localDirs": ["${global.root_dir}/workspace/skills"]
      }
    },
    {
      "type": "builtin",
      "name": "browser_use",
      "config": {
        "headless": false
      }
    }
  ]
}

子智能体工具 (agent) ​

调用其他智能体作为工具：

json
{
  "tools": [
    {
      "type": "agent",
      "name": "图片识别",
      "targetId": "agent01",
      "description": "图片识别和理解专家"
    },
    {
      "type": "agent",
      "name": "客服",
      "targetId": "agent02",
      "description": "客服支持"
    }
  ]
}

规则链工具 (rulechain) ​

调用指定规则链：

json
{
  "tools": [
    {
      "type": "rulechain",
      "name": "数据处理",
      "targetId": "chain_data_process",
      "description": "数据清洗和转换"
    }
  ]
}

通过 API 管理 ​

列出智能体 ​

bash
GET /api/v1/agents

获取智能体 ​

bash
GET /api/v1/agents/main

创建智能体 ​

bash
POST /api/v1/agents
Content-Type: application/json

{
  "ruleChain": {
    "id": "my-agent",
    "name": "我的智能体"
  },
  "metadata": {...}
}

更新智能体 ​

bash
PUT /api/v1/agents/my-agent
Content-Type: application/json

{...}

删除智能体 ​

bash
DELETE /api/v1/agents/my-agent

重载智能体 ​

bash
POST /api/v1/agents/my-agent/reload

相关文档 ​

基于 Apache-2.0 许可发布

Copyright © 2026-present TPCLAW Team