Agent Runtime 代理运行时

核心概念

OpenClaw 运行一个"单一嵌入式代理运行时"，使用专用工作空间。它将引导文件如 AGENTS.md 和 SOUL.md 注入到上下文中。

工作机制

1. 单一运行时架构

┌─────────────────┐
│   Agent Runtime │
├─────────────────┤
│  • 单一实例运行  │
│  • 专用工作空间  │
│  • 上下文注入    │
└─────────────────┘

2. 引导文件注入

系统自动注入以下引导文件到代理上下文：

• AGENTS.md: 代理配置和元数据
• SOUL.md: 代理个性和行为定义

3. 技能加载机制

技能可以从以下位置加载：

• Bundled: 内置技能包
• Local: 本地开发技能
• Workspace: 工作空间技能

4. 会话管理

• 会话以 JSONL 格式存储
• 支持会话持久化和恢复
• 提供会话状态管理

5. 消息注入控制

Steering 机制允许在工具调用期间注入消息，实现更精细的控制。

配置选项

runtime:
  workspace: "~/.openclaw/workspace"
  session_storage: "jsonl"
  bootstrap_files:
    - "AGENTS.md"
    - "SOUL.md"
  skill_paths:
    - "./skills"
    - "~/.openclaw/skills"

使用示例

启动代理运行时

openclaw agent start

查看运行时状态

openclaw agent status

管理工作空间

# 列出工作空间
openclaw agent workspace list

# 切换工作空间
openclaw agent workspace switch <workspace_name>

最佳实践

1. 工作空间隔离: 为不同项目使用独立工作空间
2. 引导文件定制: 根据业务需求定制 SOUL.md
3. 技能模块化: 将复杂功能拆分为独立技能包
4. 会话管理: 合理设置会话超时和清理策略

故障排除

常见问题

1. 技能加载失败

   检查技能路径配置和文件权限
   

2. 会话恢复异常

   检查 JSONL 文件格式和存储路径
   

3. 上下文注入失效

   验证引导文件存在且格式正确
   

调试命令

# 查看详细日志
openclaw logs --level debug

# 验证配置
openclaw config validate

# 测试连接
openclaw agent test

更多详情请参考官方文档: https://docs.openclaw.ai/concepts/agent.md