OpenClaw四种角色详解

OpenClaw对话系统使用四种核心角色：system、user、assistant、tool。这些角色构成了完整的AI交互体系。

一、角色概览

角色	发送者	作用	使用频率	内容特点
system	开发者/系统	定义AI的身份、能力、行为规范	一次/会话	长期稳定，很少变化
user	用户	提出需求、问题、指令	频繁	具体、多变、任务导向
assistant	AI助手	回应、执行、思考	频繁	专业、友好、解决问题
tool	工具执行结果	报告工具调用结果	中等	结构化数据、事实性

有兴趣的朋友可以到我的知识星球"小龙虾孵化实验室 "，里面有OpenClaw原封不动的完整提示词和完整的工具定义。
有了榜样的参照，你也能做出一个强大的自己能随意定义的龙虾。

二、详细解析

1. system - 系统定义者

作用：定义AI的基本身份和行为规范，相当于"灵魂"。

特点：

一次性设置：通常在每个会话开始时设置一次
长期有效：在整个对话中持续影响AI行为
不可见：用户看不到system消息，但能感受到其影响

典型内容：

json 复制代码

{
  "role": "system",
  "content": "你是一个专业的AI助手，擅长代码编写、文档分析和问题解答。你的回答应该简洁、准确、专业。你有以下工具可用：read_file, write_file, run_command..."
}

在OpenClaw中的实际应用：

json 复制代码

"content": "You are a personal assistant running inside OpenClaw.\n## Tooling\nTool availability (filtered by policy):\nTool names are case-sensitive. Call tools exactly as listed.\n- read: Read file contents\n- write: Create or overwrite files\n..."

设计要点：

清晰的身份：明确告知AI"你是谁"
完整的能力说明：列出所有可用工具和技能
行为规范：定义回答风格、安全规则
工作环境：告知运行环境、工作目录等

2. user - 需求提出者

作用：用户表达需求、提出问题、发出指令。

特点：

内容多样：从简单问题到复杂任务
语境相关：依赖system角色定义的行为框架
触发行动：user消息是AI行动的主要触发器

典型内容：

json 复制代码

{
  "role": "user", 
  "content": "帮我读取文件D:/work/project/src/main.js的内容"
}

在OpenClaw中的实际应用：

json 复制代码

{
  "role": "user",
  "content": "分析一下这个日志文件，找出错误信息：D:/logs/error.log"
}

设计要点：

明确具体：越具体的问题得到越准确的回答
提供上下文：必要时提供背景信息
任务导向：说明需要AI做什么

3. assistant - 问题解决者

作用：AI的回应，包括思考、执行工具、提供答案。

特点：

响应式：总是对user消息的回应
工具调用：可以通过特殊格式调用工具
结构化思考：可以包含思考过程和最终答案

典型内容：

json 复制代码

{
  "role": "assistant",
  "content": "我来帮你读取这个文件。\n\n<tool_calls>\n<tool_call>\n<tool_name>read_file</tool_name>\n<args>\n<filePath>D:/work/project/src/main.js</filePath>\n</args>\n</tool_call>\n</tool_calls>"
}

在OpenClaw中的实际应用：

json 复制代码

{
  "role": "assistant",
  "content": "好的，我来帮你分析飞书日程。\n\n<tool_calls>\n<tool_call>\n<tool_name>feishu_calendar_event</tool_name>\n<args>\n<action>list</action>\n<calendar_id>primary</calendar_id>\n<time_min>2026-04-01T00:00:00+08:00</time_min>\n</args>\n</tool_call>\n</tool_calls>"
}

设计要点：

自然语言：保持友好专业的语气
工具调用规范：严格遵循工具调用格式
分步说明：复杂任务时说明步骤
错误处理：工具失败时提供备用方案

4. tool - 执行报告者

作用：报告工具执行的结果。

特点：

数据驱动：包含结构化数据或执行状态
事实性：提供客观事实，不添加主观解释
链接性 ：通过tool_call_id与assistant的工具调用关联

典型内容：

json 复制代码

{
  "role": "tool",
  "content": "文件内容：\nfunction main() {\n  console.log('Hello World');\n}",
  "tool_call_id": "call_abc123"
}

在OpenClaw中的实际应用：

json 复制代码

{
  "role": "tool",
  "content": "{\"events\": [{\"id\": \"123\", \"summary\": \"团队周会\", \"start\": \"2026-04-01T10:00:00+08:00\", \"end\": \"2026-04-01T11:00:00+08:00\"}]}",
  "tool_call_id": "call_xyz789"
}

设计要点：

准确完整：提供完整的执行结果
结构化数据：复杂数据使用JSON格式
错误报告：工具失败时提供错误详情
引用关联：通过tool_call_id正确关联

三、完整的对话流程示例

场景：读取文件并分析

json 复制代码

// 1. system - 定义AI（仅一次）
{
  "role": "system",
  "content": "你是OpenClaw助手，可以读取和分析文件..."
}

// 2. user - 提出需求
{
  "role": "user",
  "content": "读取D:/work/data.txt并告诉我文件大小"
}

// 3. assistant - 思考并调用工具
{
  "role": "assistant",
  "content": "我来读取文件。\n\n<tool_calls>\n<tool_call>\n<tool_name>read_file</tool_name>\n<args>\n<filePath>D:/work/data.txt</filePath>\n</args>\n</tool_call>\n</tool_calls>"
}

// 4. tool - 报告读取结果
{
  "role": "tool",
  "content": "文件内容：...\n文件大小：2048字节",
  "tool_call_id": "call_123"
}

// 5. assistant - 分析并回应
{
  "role": "assistant", 
  "content": "文件读取成功。文件大小为2048字节（2KB），内容包含..."
}

四、技术实现细节

1. 角色管理机制

javascript 复制代码

// 伪代码：角色管理
class Conversation {
  constructor() {
    this.messages = [];
  }
  
  addSystemPrompt(content) {
    this.messages.push({
      role: 'system',
      content: content
    });
  }
  
  addUserMessage(content) {
    this.messages.push({
      role: 'user', 
      content: content
    });
  }
  
  addAssistantMessage(content, toolCalls = []) {
    const message = {
      role: 'assistant',
      content: content
    };
    
    if (toolCalls.length > 0) {
      message.tool_calls = toolCalls;
    }
    
    this.messages.push(message);
  }
  
  addToolResult(toolCallId, content) {
    this.messages.push({
      role: 'tool',
      tool_call_id: toolCallId,
      content: content
    });
  }
}

2. 工具调用格式

OpenAI标准格式：

json 复制代码

{
  "role": "assistant",
  "content": "思考内容...",
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "read_file",
        "arguments": "{\"filePath\": \"/path/to/file\"}"
      }
    }
  ]
}

简化版AI/OpenClaw格式：

json 复制代码

{
  "role": "assistant",
  "content": "思考内容...\n\n<tool_calls>\n<tool_call>\n<tool_name>read_file</tool_name>\n<args>\n<filePath>/path/to/file</filePath>\n</args>\n</tool_call>\n</tool_calls>"
}

3. 上下文窗口管理

javascript 复制代码

// 上下文长度限制（以deepseek-v3.2为例）
const CONTEXT_WINDOW = 32000; // tokens

// 角色消耗估算（每个token约0.75英文单词）
const estimateTokens = (messages) => {
  let total = 0;
  
  messages.forEach(msg => {
    // system: 约5000 tokens（完整系统提示词）
    // user: 每个消息约100-500 tokens
    // assistant: 每个消息约200-1000 tokens
    // tool: 每个消息约50-500 tokens
  });
  
  return total;
};

// 截断策略：优先保留最近的user/assistant对话

五、最佳实践

1. system角色设计

** 好的设计**：

json 复制代码

{
  "role": "system",
  "content": "你是OpenClaw助手，擅长文件操作和数据分析。\n可用工具：read_file, write_file, run_command\n安全规则：不执行危险命令\n工作目录：C:/work"
}

** 不好的设计**：

json 复制代码

{
  "role": "system", 
  "content": "你是助手"  // 太简单，缺乏指导
}

2. 对话流程优化

多轮对话示例：

复制代码

system: 定义AI
user: 需求1
assistant: 思考 → 调用工具1
tool: 结果1
assistant: 分析结果1 → 调用工具2  
tool: 结果2
assistant: 综合回答
user: 追问
assistant: 进一步分析...

3. 工具结果处理

** 正确处理**：

json 复制代码

// assistant调用
{
  "role": "assistant",
  "content": "读取文件...",
  "tool_calls": [{"id": "call_1", "function": {"name": "read_file"}}]
}

// tool结果
{
  "role": "tool",
  "tool_call_id": "call_1",  // 正确关联
  "content": "文件内容..."
}

** 错误处理**：

json 复制代码

{
  "role": "tool",
  "tool_call_id": "wrong_id",  // 关联错误
  "content": "..."
}

六、常见问题与解决方案

Q1: system角色可以修改吗？

可以，但不推荐频繁修改。system定义AI的"人格"，修改可能导致行为不一致。如需调整，最好创建新会话。

Q2: 如何让AI记住之前对话？

通过保留对话历史实现：

javascript 复制代码

// 保留最近N轮对话
const keepRecentMessages = (messages, n) => {
  return [messages[0]]  // system
    .concat(messages.slice(-n*2));  // 最近n轮user+assistant
};

Q3: tool角色必须返回成功结果吗？

不是。tool可以返回：

成功结果：{"status": "success", "data": ...}
失败结果：{"status": "error", "error": "文件不存在"}
部分结果：{"status": "partial", "data": ...}

Q4: 如果工具调用失败怎么办？

json 复制代码

// assistant应处理错误
{
  "role": "assistant",
  "content": "工具调用失败，尝试备用方案...\n\n<tool_calls>\n<tool_call>\n<tool_name>alternative_tool</tool_name>\n</tool_call>\n</tool_calls>"
}

七、总结

四种角色构成了完整的AI协作体系：

system - 定义者：设定规则和边界
user - 发起者：提出需求和问题
assistant - 决策者：思考、计划、调用工具
tool - 执行者：执行任务，上报执行结果

核心协作模式：

复制代码

system → 定义框架
user → 触发任务  
assistant → 计划执行 → 调用tool
tool → 返回事实
assistant → 综合分析 → 回答user

关键设计原则：

角色清晰：每个角色有明确职责
数据流动：信息在各角色间正确传递
错误处理：每个环节都有容错机制
上下文管理：合理控制对话长度

理解这四种角色的协作机制，是设计和实现高效AI助手系统的基础。