role_config.yaml

openclaw openclaw官方 2026-04-09 1

设置方法主要分为 “一次性角色设定” 和 “动态角色管理” 两种模式，具体取决于你的使用场景和OpenClaw的实现版本。

role_config.yaml-第1张图片-OpenClaw开源下载|官方OpenClaw下载

核心原理：基于提示工程的“系统指令”

无论哪种方法,本质都是构建一个强大的 系统提示词（System Prompt），在对话开始前注入给大模型（如GPT），定义其行为基线，OpenClaw通常将角色设定作为系统提示的核心部分。

一个完整的角色设定应包含以下层次：

身份与背景

你是谁：给智能体一个明确的身份（如：资深网络安全分析师、体贴的私人健康助手、严谨的学术论文编辑）。
你的背景：赋予其相关的知识领域、经验和价值观。

核心职责与目标

你的核心任务：清晰说明智能体被创造出来的主要目的（如：“帮助用户分析和缓解潜在的网络安全威胁”、“为用户提供基于科学证据的健康生活建议”）。
你的目标：更具体、可衡量的目标（如：“确保每次回答都提供可操作步骤”、“优先考虑用户数据的隐私和安全”）。

行为规范与风格

沟通风格：语气是专业、热情、简洁还是鼓励式？
响应格式：是否使用分点、表格、代码块？是否在结尾总结？
边界与限制：什么不能做？遇到无法处理或超出范围的问题时如何回应？（“对于医疗诊断或财务投资建议，你应明确声明自己的局限性并建议用户咨询持证专家。”）

工具使用规范

工具认知：告诉智能体它拥有哪些“能力”（即可以调用的工具/函数），如 search_web、query_database、execute_code、analyze_file 等。
使用规则：何时以及如何使用这些工具，这是OpenClaw这类智能体的关键。（“当用户的问题需要最新信息时，你应优先使用 search_web 工具。” “在提供代码解决方案后，如果用户要求，你可以使用 execute_code 工具进行验证。”）

具体设置方法

根据OpenClaw的实现方式,你可以通过以下途径进行角色设置：

方法A：配置文件/YAML定义（适用于开发者/一次部署）

这是最常用、最结构化的方法，通常会在项目根目录或 config/ 文件夹下有一个角色配置文件。

description: "一个专注于主动威胁狩猎和事件响应的AI安全分析助手。"
system_prompt: |
  你是一个名为CyberGuardian的AI，是一名拥有10年经验的虚构首席安全官。
  **核心职责**：
  1.  分析用户描述的安全事件或疑虑。
  2.  提供循序渐进的安全加固建议。
  3.  解释复杂的安全概念，使之易于理解。
  **行为规范**：
  - 语气保持冷静、专业且富有同理心，理解安全事件会给用户带来压力。
  - 所有安全建议应遵循最小权限原则和纵深防御理念。
  - 如果遇到可能的紧急威胁（如：勒索软件活动、数据泄露），需在回答开头强烈建议用户立即隔离系统并联系专业团队。
  **可用工具**：
  1.  `threat_intel_query`： 查询最新的威胁情报指标。
  2.  `cve_lookup`： 获取CVE漏洞的详细信息。
  3.  `log_analyzer`： 对提供的日志片段进行模式分析（需用户上传）。
  **工具使用规则**：
  - 当用户提到具体的恶意软件名称、IP地址或哈希值时，使用 `threat_intel_query`。
  - 当讨论软件漏洞时，使用 `cve_lookup` 获取详细信息。
  - 优先基于你的知识进行推理，仅在需要**最新、具体**数据时才调用工具。
  **禁止事项**：
  - 绝不提供可用于非法入侵的详细步骤。
  - 不替代专业的事件响应服务。
response_format: "以清晰的分点列出关键发现和建议，重要警告使用【！】标识。"

在启动OpenClaw智能体时,加载此配置文件。

方法B：管理界面/对话初始化（适用于终端用户/动态切换）

如果OpenClaw提供了Web界面或客户端,通常会有：

“角色市场”：选择预制的角色（如“代码专家”、“创意写手”）。
“自定义角色”创建：一个表单或文本框，让你填写上述各个部分。
会话开始时指定：在首次对话中，用户可以直接用自然语言描述期望的角色。
- 用户输入： “请你扮演一位严厉但公正的英语语法老师，专门纠正我的商务邮件写作，请直接指出错误并解释规则，不要过度夸奖。”
- OpenClaw：理解指令，并将此设定转化为系统提示，应用于本次会话。

方法C：API调用参数（适用于程序化集成）

如果你通过API调用OpenClaw智能体,角色设定通常作为API请求的一个参数传递。

import requests
api_url = "https://api.openclaw.example.com/v1/chat/completions"
api_key = "your_api_key"
# 角色设定放在 `system` 消息中
messages = [
    {
        "role": "system",
        "content": "你是OpenClaw公司的官方客服助手Leo，你的风格友好、耐心且高效，主要任务是处理产品咨询、故障排查和预约演示，对于无法解决的问题，务必收集用户联系方式并承诺让专人回复，你可以访问知识库（使用`search_kb`工具）来获取最新产品信息。"
    },
    {
        "role": "user",
        "content": "我的设备XYZ连接不上云服务了，怎么办？"
    }
]
payload = {
    "model": "openclaw-agent",
    "messages": messages,
    "tools": [ ... ] # 工具函数定义列表
}
headers = {"Authorization": f"Bearer {api_key}"}
response = requests.post(api_url, json=payload, headers=headers)

最佳实践与建议

从简开始，迭代优化：先定义一个核心身份和目标，在测试中观察智能体的行为，逐步添加约束和优化描述。
明确工具使用触发词：在角色描述中，清晰地定义调用每个工具的条件，这能显著提高智能体使用工具的准确性和必要性。
使用“负面提示”：明确“不要做什么”有时比“要做什么”更有效，尤其是在安全和合规方面。
利用“角色”来限制幻觉：通过将角色限定在特定领域（如“你是一位历史学家”），可以降低模型在无关领域胡编乱造的概率。
测试与评估：
- 一致性测试：多次询问相同类型的问题，看回答是否符合角色设定。
- 边界测试：询问角色范围外的问题，看其是否会得体地拒绝或转移话题。
- 工具调用测试：设计需要特定工具才能完美回答的问题，检验其调用逻辑是否正确。