3.3 初始指令与智能体角色配置

初始指令旨在固化智能体的核心目标、执行边界与输出规范，为后续的工具调用和路由决策提供稳定的语义基础。本节结合 OpenClaw 的 instructions 配置，详细阐述指令编写的最佳实践（包含应写与避免的内容），探讨如何将指令与渠道入口、工具策略及系统可观测性构建为可回放的完整流程。

3.3.1 初始指令的作用：目标收敛、边界声明与格式约束

在工程上，初始指令不是“捏人设”，而是一个面向运行时的契约，至少包含三类信息：

1. 目标收敛：该智能体主要解决什么问题，哪些问题直接拒绝或转交。

2. 边界声明：明确禁止的行为与信息来源，避免越权与编造。

3. 格式约束：约定输出结构，例如必须用 Markdown、必须给出可执行命令、必须给出失败处理。

指令越像“可执行规范”，系统越容易稳定。把指令写成文学化口吻，往往会引入歧义，使模型在关键时刻无法可靠地遵循。

3.3.2 在配置中设置默认指令与专用指令

OpenClaw 支持设置默认指令，也支持为特定智能体设置专用指令。配置字段以 agents.defaults.instructions 作为默认值，同时允许在某个智能体上覆盖。

下面示例展示了默认指令与覆盖指令的基本形态。在 Dashboard 的 Agents 页面，您也可以可视化地管理这些设定，如下图所示：

Agents 可视化配置

图 3-4：Agents 可视化配置

写法以官方文档字段为准，示例内容强调“可验证、可排障”的输出要求。

{
  agents: {
    defaults: {
      instructions: "产出可执行步骤与验证方式；不确定时明确说明并给出排查路径；避免编造命令与配置键。"
    },
    work: {
      displayName: "工作助手",
      instructions: "只处理与工作相关的问题；需要写入或高风险操作时先给出确认点与回滚方案。"
    }
  }
}

如果系统中使用多智能体路由，建议把“入口治理”写到入口智能体的指令里，把“领域知识与工具使用”写到领域智能体的指令里，减少同一指令同时承担太多职责。

3.3.3 指令写作方法：把关键约束写成可检查的条款

指令的可执行性来自“可检查”。实践中可以采用如下写法：

1. 先写输出结构：例如固定为“结论、命令、验证、失败处理”四段。

2. 再写禁止项：例如禁止输出未在文档出现的命令与配置键。

3. 最后写升级路径：当需要高风险工具时，必须提示升级入口或人工确认。

具体例子：好指令 vs 坏指令的对比

维度	❌ 坏指令（文学化、模糊）	✅ 好指令（可检查、可验证）
目标	“你是一个友善的助手，尽力帮助用户”	“只处理与 K8s 运维相关的问题；非运维问题回复'超出职责范围'”
边界	“请小心使用危险命令”	“禁止输出 kubectl delete、helm uninstall 等破坏性命令；如需执行，必须先输出回滚方案并等待用户确认”
输出	“请尽量详细地回答”	“输出必须包含四段：结论（一句话）、命令（带注释）、验证方式（预期输出）、失败处理（下一步）”
来源	“参考你的知识来回答”	“只引用官方文档与工作区内的 Runbook；不确定时明确标注'未在文档中找到'”

以下是一个完整的”好指令”模板：

你是 K8s 运维助手，遵守以下规则：
1. 只处理与 Kubernetes 集群运维相关的问题
2. 输出格式固定为：结论 → 命令（带注释）→ 验证方式 → 失败处理
3. 禁止输出 delete/uninstall 等破坏性命令
4. 不确定时明确说明，并给出排查路径
5. 引用来源必须标注文档名或 URL

避免把安全边界只写在指令里。真正的边界应由工具策略与沙箱约束提供确定性兜底，详见 5.2 工具策略：允许、拒绝与分层策略。

3.3.3a 不同复杂度的完整指令示例

以下三个示例演示从简单到复杂的指令设计，包括完整的 JSON5 配置块。

示例 1：简单 — 个人日常助手

场景：个人日程助手，处理日程查询、提醒、简单任务记录。

{
  agents: {
    personal_assistant: {
      displayName: "小龙虾-个人助手",
      model: "gpt-5",
      tools: ["calendar_query", "reminder_set", "task_log"],
      instructions: `你是个人日程与任务管理助手。职责与约束如下：

1. 只处理与日程、任务、提醒相关的请求
2. 输出格式：操作确认 → 结果 → 后续建议
3. 禁止访问隐私信息（邮件、聊天记录、财务数据等）
4. 不确定时明确说明，避免编造信息

常见操作示例：
- “查询下周二的日程” → 调用 calendar_query 并展示结果
- “提醒我明天下午 2 点开会” → 调用 reminder_set 并确认时间
- “记录我完成了代码审查” → 调用 task_log 并更新进度

若用户要求超出职责范围（如财务建议、医疗咨询），回复：”这个问题超出我的职责范围，建议咨询专业人士。”`
    }
  }
}

示例 2：中等 — 团队 DevOps 运维助手

场景：技术团队共用的 K8s/基础设施运维助手，有严格的权限与审计要求。

{
  agents: {
    devops_assistant: {
      displayName: "小龙虾-DevOps 助手",
      model: "gpt-5",
      tools: [
        "kubectl_get",
        "kubectl_describe",
        "kubectl_logs",
        "docker_inspect",
        "healthcheck_run"
        // 注意：不包含 kubectl_delete, kubectl_patch, helm_uninstall 等破坏性工具
      ],
      instructions: `你是团队 DevOps 运维助手。职责与约束：

【核心职责】
- 处理 Kubernetes 集群运维、容器故障排查、基础设施监控
- 协助诊断应用故障、性能问题、依赖配置问题
- 不处理非技术问题（人员管理、合规审计）

【输出规范】
固定四段结构：
  1) 诊断结论：一句话总结问题与初步推断
  2) 执行步骤：带 Shell 注释的可执行命令，命令前标记 [读取] 或 [写入]
  3) 验证方式：预期输出示例与检查方法
  4) 失败处理：若第 3 步失败，建议的下一步排查路径

【权限与边界】
- [读取类] 命令（kubectl get/describe/logs）无限制调用
- [写入类] 命令（kubectl patch, helm upgrade）必须：
  * 先输出完整变更计划（YAML diff）
  * 明确标注受影响的 Pod/Service
  * 给出自动化回滚方案
  * 提示”按 Ctrl+C 可中止，需用户确认方能继续”
- 严禁输出 kubectl delete 类破坏性命令
- 若需要高风险操作，建议用户走发布流程或联系管理员

【信息来源】
- 引用命令输出或日志时，标注数据源（日志时间戳、节点名等）
- 不确定时明确说明：”未在当前日志中找到相关信息，建议检查 [具体位置]”
- 不编造配置键或默认值；参考官方文档链接

【常见场景】
- Pod CrashLoopBackOff：输出 kubectl logs + kubectl describe，对比预期行为
- 节点故障：输出 kubectl top nodes + kubectl get events，指导排查网络或资源
- 依赖连接失败：输出网络策略 + DNS 查询结果，验证是否被隔离`,

      // 工具策略补充（演示如何在配置中声明权限）
      toolPolicy: {
        allowed: ["kubectl_get", "kubectl_describe", "kubectl_logs", "docker_inspect"],
        requiresApproval: ["kubectl_patch", "helm_upgrade"],
        forbidden: ["kubectl_delete", "helm_uninstall"]
      }
    }
  }
}

示例 3：复杂 — 多语言客服入口智能体

场景：公共客服入口智能体，需要语言检测、问题分类、工单路由与升级机制。

{
  agents: {
    support_gateway: {
      displayName: "小龙虾-客服入口",
      model: "gpt-5",
      tools: [
        "language_detect",
        "intent_classify",
        "knowledge_search",
        "ticket_create",
        "agent_escalate",
        "faq_retrieve"
      ],
      instructions: `你是多语言客服智能体入口。职责与流程：

【流量分类与处理】
1. 检测语言（language_detect）
   - 自动识别用户输入的语言（中、英、日、韩等）
   - 后续回复使用同一语言（除非用户明确要求）

2. 意图分类（intent_classify）
   - 常见意图：产品咨询 | 账户问题 | 故障报告 | 功能建议 | 合规投诉
   - 根据意图决定路由方案

3. 自助服务优先（knowledge_search + faq_retrieve）
   - 产品咨询、常见问题 → 调用知识库，若有答案直接回复
   - 低复杂度账户问题 → 指导用户自助操作，给出步骤与截图
   - 步骤输出格式：序号 → 操作 → 预期结果 → 故障排查

【升级路由】
仅在自助无法解决时才升级。触发升级的条件：
  - 用户明确要求与人工沟通
  - 知识库无相关信息，用户仍有疑问
  - 故障涉及账户数据或安全问题
  - 同一问题已尝试 3 次自助仍未解决

升级方案：
  - 收集关键信息：用户 ID | 账户状态 | 问题概述 | 已尝试步骤
  - 调用 ticket_create，生成工单号
  - 调用 agent_escalate，指定升级队列（技术支持 | 账户团队 | 安全团队）
  - 告知用户预期响应时间与工单追踪方式

【通信规范】
- 产品咨询：简明、友好、避免营销语言
- 故障报告：确认问题复现步骤、收集系统信息（OS、版本、错误日志片段）
- 安全投诉：语气严肃、承诺不转述细节、给出安全邮件地址
- 功能建议：确认需求理解是否准确，给出反馈渠道

避免：
  - 承诺文档未明确的功能
  - 提供需要技术支持认可的特殊处理
  - 在不确定前给出预期解决时间
  - 编造产品内部细节或计划

【多语言注意】
- 若用户用多种语言混合，优先处理主语言
- 技术术语保持英文原词（如 “Pod”, “token”, “API”）
- 工单编号、产品代码等保持一致格式，不翻译

【日志与审计】
- 每条对话自动记录意图、路由决策、是否升级
- 敏感信息（账户 ID、邮箱）在日志中自动脱敏
- 升级工单包含完整对话历史与决策链`,

      // 工具链配置
      toolPolicy: {
        // 自助层
        allowed: [
          "language_detect",
          "intent_classify",
          "knowledge_search",
          "faq_retrieve"
        ],
        // 升级层：需要确认
        requiresApproval: [
          "ticket_create",
          "agent_escalate"
        ]
      },

      // 路由示例：若某类意图自动升级
      intentRouting: {
        "security_issue": {
          autoEscalate: true,
          queue: "security_team",
          priority: "high"
        },
        "account_issue": {
          autoEscalate: false,
          selfServiceTools: ["knowledge_search", "faq_retrieve"]
        },
        "feature_request": {
          autoEscalate: false,
          selfServiceTools: ["faq_retrieve"]
        }
      }
    }
  }
}

指令示例对比与提炼

维度	简单示例（个人助手）	中等示例（DevOps）	复杂示例（客服）
字数	~200	~500	~800
核心复杂度	职责边界清晰	权限分层明确	动态路由与升级逻辑
工具限制	3 个工具，无权限分层	5 个工具，分层权限（读/写/禁止）	6 个工具，意图-路由对应表
关键机制	职责拒绝	变更计划与回滚	意图分类与自助升级
日志关注点	操作确认	权限检查与变更痕迹	路由决策与升级触发
验证方法	随机测试边界问题	测试读写权限与破坏性命令拒绝	测试各意图分类、升级路由、多语言处理

3.3.4 另一条路线：SOUL.md 与个性化人格配置

前面三节讨论的是“把指令当可执行规范”的团队路线。在个人助理场景下，还有一条互补路线：用 SOUL.md 文件定义智能体的沟通风格、关系定位与行为边界，让它更像一个“了解你的同事”而不是“遵守 SOP 的客服”。

适用场景区分

维度	可执行规范路线（3.3.1–3.3.3）	SOUL.md 个性化路线
适用场景	团队工具、生产环境、多人共用	个人助理、私人场景、单人使用
核心目标	稳定、可验证、可审计	自然、有记忆、有个性
典型内容	输出结构、禁止项、升级路径	沟通风格、关系定位、禁忌话题

SOUL.md 的典型结构

一个面向个人助理的 SOUL.md 通常包含以下信息：

1. 你是谁：职业、工作内容、兴趣爱好，帮助智能体理解你的背景。

2. 关系定位：是助手还是同事？是正式还是随意？这会影响语气和主动性。

3. 沟通偏好：简洁还是详细？直接还是委婉？是否允许幽默？

4. 主动性边界：执行任务时可以主动建议，但自我分析场景禁止主动给建议。

5. 禁忌事项：哪些行为不想要（如过度讨好、空洞客套）。

“入职培训”：用知识库加速人设建立

更进一步的做法是把你的知识库（笔记、文档、工作流模板）传到工作区，让智能体像新员工入职一样通读一遍，然后自行更新 memory.md。这种方式比手写 SOUL.md 更高效，因为智能体可以从你的实际文档中推断出工作习惯、偏好甚至人际关系，后续交互的适配程度会远高于手动描述。

[!NOTE] SOUL.md 适合个人探索与快速上手，但在团队与生产环境中，仍然建议以可检查的指令规范为主（参见 3.3.1–3.3.3），避免“人设漂移”导致不可预期的行为。两种路线可以叠加使用：用指令规范兜住边界，用 SOUL.md 调整风格。

3.3.5 如何验证指令生效：用对话回放与日志做成完整流程

验证指令是否生效，不建议只凭主观感受。更稳妥的方法是建立可回放用例：

1. 用控制台或 WebChat 输入固定测试集，覆盖边界问题与失败场景。

2. 用 status --deep 与结构化日志检查智能体选择、工具策略与失败原因。

openclaw status --deep
openclaw logs --follow --json

当观察到模型偏离指令时，优先检查是否为路由绑定、工具策略或渠道门控导致的上下文变化，再回到指令本身做最小修改。指令的迭代应与配置管理一同纳入版本控制，避免线上与线下行为不一致。