openclaw-control-center/docs/FAQ.md

常见问题与最佳实践 / FAQ & Best Practices

Looking for English? See FAQ Guide (English) below.

中文版

1. 多 Agent 工作区 — 为什么成员列表看不到职责 / 显示“工作区未写明职责”？

问题： 已经在 SOUL.md 和 AGENTS.md 中写好了角色和职责，但控制中心的员工页面看不到具体分工。

直接回答： 员工页当前不会直接把某个配置文件里的 role / mission 字段原样摘出来显示。它更依赖 workspace 目录、IDENTITY.md 这类身份线索，以及 Gateway 返回的运行时元信息。

常见原因： 控制中心会参考 OpenClaw 的 workspace 目录和运行时信号。是否能看到完整职责信息，通常取决于：

• OpenClaw Gateway 返回的 session 数据中是否包含 agent 元信息
• OPENCLAW_AGENT_ROOT 环境变量是否指向了正确的 workspace 目录

解决方法：

1. 确认 workspace 目录结构正确：

   workspace-你的agent名/
   ├── SOUL.md          # 性格和角色定义
   ├── IDENTITY.md      # 名字、emoji 等身份信息
   ├── AGENTS.md        # 多 agent 协作规则
   └── MEMORY.md        # 长期记忆
   

2. 检查环境变量：

   # 确保 OPENCLAW_AGENT_ROOT 指向包含所有 workspace 的父目录
   export OPENCLAW_AGENT_ROOT=/path/to/.openclaw
   

3. 确认 Gateway 正在运行：

   openclaw gateway status
   

   控制中心通过 Gateway API 获取 agent 列表和状态。如果 Gateway 没运行，员工页会显示空白或错误。

4. 员工页信息通常会参考这些来源：

   • 名字/emoji → 常见做法是放在 IDENTITY.md
   • 状态（执行中/空闲） → 主要来自 Gateway 的 session 运行信号
   • workspace → 通常来自 agent 配置中的 workspace 字段
   • 具体职责描述 → 当前不会自动把 SOUL.md 摘要直接显示成员工卡片文案，更适合作为文档线索保存在 IDENTITY.md、SOUL.md、AGENTS.md
   • 不会直接摘取的内容 → 任意配置文件里自定义的 role / mission 文本，目前不会被员工卡片逐字渲染成职责说明

最佳实践： 如果你希望控制中心更容易展示身份与职责线索，建议优先把简短身份说明写进 IDENTITY.md，并把详细角色说明写进 SOUL.md / AGENTS.md。

---

2. 订阅/账单 — 数据怎么接？限额在哪设置？

问题： 用量页面有费用数据，但不知道这些数据从哪来、限额怎么设置。

数据来源（常见情况）：

控制中心的主要用量数据通常来自 OpenClaw Gateway，不需要额外接入第三方账单系统。

OpenClaw Gateway → 记录每次 API 调用的 token 用量
                 → 根据模型定价计算费用
                 → 控制中心通过 API 拉取显示

限额设置方式（最佳实践）：

预算/限额通常在你的 OpenClaw 配置里设置，而不是在控制中心 UI 里直接填写。具体字段名和写法，请以你当前使用的 OpenClaw 版本与官方文档为准。

下面这段可以作为常见示例理解，不要把它当成所有环境都完全一致的唯一标准：

# 常见示例：在 OpenClaw 配置中设置 budget
# 具体字段请以你的 OpenClaw 版本为准

budget:
  # Token 限额
  tokensIn: 1000000
  tokensOut: 500000
  totalTokens: 1500000

  # 费用限额（美元）
  cost: 50.00

  # 预警比例（达到此比例时发出警告）
  warnRatio: 0.8

控制中心显示的内容：

• 用量页 → Token 消耗： 按 agent、按模型、按时间段的 token 使用
• 用量页 → 费用： 基于模型定价的预估费用
• 用量页 → 上下文压力： 哪些 session 接近上下文窗口上限
• 总览页 → 预算摘要： 当前用量 vs 限额的进度条

最佳实践： 如果你希望控制中心看到更完整的一致用量，建议尽量通过 OpenClaw Gateway 统一管理 API 调用。

---

3. 会话停滞检测 — 怎么判定的？

问题： 控制中心显示某个会话"停滞执行"，但找不到是哪个会话，也不确定判定标准。

判定逻辑（控制中心视角）：

控制中心会根据当前拿到的运行信号，把会话整理成类似下面这些可读状态：

状态	英文	判定条件
执行中	running	会话有活跃的 API 调用或工具执行
空闲	idle	会话存在但没有活跃任务
阻塞	blocked	会话等待外部输入或资源
等待审批	waiting_approval	会话需要用户手动确认才能继续
错误	error	会话遇到错误

“停滞执行”通常表示： 控制中心看到某个会话仍在运行态，但最近缺少新的活动信号，因此将它标记为疑似停滞。常见参考信号包括：

1. Gateway 层面： OpenClaw Gateway 跟踪每个 session 的最后活跃时间
2. 控制中心层面： 定期轮询 Gateway，比较 running 状态会话的最后活跃时间
3. 健康检查： 某些环境里还会结合健康状态或 freshness 信号

如何进一步确认：

# 查看所有 running 状态的 sessions
openclaw sessions list --filter running

# 查看特定 session 的详情
openclaw sessions history <session-key> --limit 5

常见处理方式：

• 如果是 heartbeat 检查导致的误判，先回到会话详情看最近活动
• 如果确实停滞了，可以尝试手动发消息恢复：

  openclaw sessions send <session-key> "继续"
  

• 如果仍无进展，再考虑终止或重启对应 session

最佳实践： 把这套流程理解成控制中心视角下的排查建议更合适，不要把它当成所有 OpenClaw 环境都完全一致的唯一底层判定标准。

---

English Version

1. Multi-Agent Workspace — Why Does the Staff Page Show "Role not defined in workspace"?

Issue: Roles defined in SOUL.md and AGENTS.md don't appear in the Control Center staff list.

Short answer: The Staff page does not currently render an arbitrary role or mission field from one config file verbatim. It relies more on workspace discovery, identity hints such as IDENTITY.md, and runtime metadata returned by Gateway.

Common guidance / best practice:

• Ensure your workspace directory follows the standard structure (SOUL.md, IDENTITY.md, AGENTS.md, MEMORY.md)
• Set OPENCLAW_AGENT_ROOT environment variable to point to the parent directory of all workspaces
• Confirm OpenClaw Gateway is running (openclaw gateway status)
• A practical best practice is to put short identity/role hints in IDENTITY.md, and longer role definitions in SOUL.md / AGENTS.md
• Do not expect a custom role / mission field from an arbitrary config file to appear as the exact Staff-card responsibility text

2. Billing & Budget — How to Connect Data and Set Limits?

Data source (common case): Most usage data shown in the Control Center comes from OpenClaw Gateway. No third-party billing integration is usually required.

Setting limits: A common best practice is to configure budget thresholds in your OpenClaw config. The exact field names depend on your OpenClaw version and setup.

The example below is a common pattern, not a universal schema for every environment:

budget:
  totalTokens: 1500000
  cost: 50.00
  warnRatio: 0.8

3. Session Stall Detection — How Does It Work?

A session is usually treated as "stalled" when the Control Center still sees it as running but recent activity signals stop updating for a while. Use openclaw sessions list --filter running to review candidates.

Best-practice next step: inspect recent session activity first, then optionally send a message to the session (openclaw sessions send <key> "continue"). If it still does not recover, terminate or restart the session. Treat this as operator guidance from the Control Center perspective, not as the only possible OpenClaw runtime rule.