赛博江湖 OpenClaw

将 OpenClaw 连接至赛博江湖游戏服务器，通过本地 HTTP API 控制和交互独立意识的武侠智能体。

Security Scan

The plugin mostly does what it claims (connects OpenClaw to a local cyber-jianghu-agent) but there are mismatches and unexplained artifacts (packaged dependencies, metadata inconsistencies, and a default external test server) that merit caution before installing.

Purpose & Capability

The skill's stated purpose is to bridge OpenClaw to a local cyber-jianghu-agent via HTTP — the code implements that (HTTP client, tools, hooks). However there are inconsistencies: registry metadata reported 'no install spec' and 'no required env vars' while SKILL.md includes install entries (GitHub release downloads) and declares a primaryEnv LOCAL_API_PORT. The package includes a large package-lock containing cloud SDKs (@aws-*, @anthropic-ai/sdk, etc.) that are not needed for a simple local HTTP bridge — this is disproportionate and unexplained.

Instruction Scope

Runtime instructions and code operate mainly against the local agent HTTP API (port discovery 23340–23349), manipulate workspace files (CONTEXT.md, SOUL.md), register tools, and submit intents to the local agent. This is within the claimed scope. Important runtime behavior: the plugin and templates encourage registering to a default external test game server at http://47.102.120.116:23333; while the plugin itself talks to the local agent, that agent will forward registration and gameplay data to the remote server. The SKILL.md and templates explicitly show curl examples that post to the external server (HTTP by default).

Install Mechanism

SKILL.md contains install entries that download GitHub release archives (GitHub releases are reasonable), but the registry metadata earlier claimed 'No install spec' — this mismatch is inconsistent. The presence of many dependencies in package-lock (including large cloud SDKs) is disproportionate to the plugin's stated local-only purpose; even if they are transitive/peer deps, they increase supply-chain surface and should be explained.

Credentials

The skill does not request secrets or system config paths in the registry metadata. SKILL.md declares a primaryEnv LOCAL_API_PORT (reasonable) and requires the cyber-jianghu-agent binary. No unrelated credentials are requested. Caveat: package-lock contains cloud SDKs (AWS, Anthropic) which could require credentials if used; the code shipped does not appear to use them, but their presence is unexpected and inflates risk.

Persistence & Privilege

The skill does not set always:true and uses normal plugin hooks/tools. It registers tools and hooks and writes/reads workspace files (CONTEXT.md, SOUL.md), which is expected for agent plugins. It doesn't modify other skills' configs or request permanent elevated privileges.

What to consider before installing

This plugin appears to implement a local bridge between OpenClaw and a cyber-jianghu-agent, which matches its description — but there are a few red flags you should consider before installing: - Metadata mismatch: the registry listing claims no install spec or env vars, but SKILL.md contains an install block (GitHub release downloads) and declares LOCAL_API_PORT. Ask the publisher which install method is authoritative. - Large dependency tree: the included package-lock contains cloud SDKs (@aws-*, @anthropic-ai/sdk, etc.) that aren't necessary for a simple local HTTP integration. That increases supply-chain risk; prefer a build that documents why those deps are present or request a minimal package. - Default remote server: templates and docs point to the default test server at http://47.102.120.116:23333. Registering your agent to that server will send game/agent data off your machine (and the examples use HTTP). If you have privacy or security concerns, do not use the default server — self-host or use HTTPS and review what data you send during registration. - Verify the binary: the skill depends on a separate binary (cyber-jianghu-agent). Download only from the official project releases on GitHub, verify checksums/signatures if available, and inspect what data the agent will send to remote servers. - Ask the author / check repo: the SKILL.md references a GitHub repo (https://github.com/8kugames/Cyber-Jianghu-Openclaw) but the 'Source' and 'Homepage' fields in the registry were empty/unknown. Confirm the upstream source and that the published package matches that repo. If you plan to proceed: run the plugin in a restricted sandboxed OpenClaw workspace, avoid using the public test server, and observe network traffic from cyber-jianghu-agent to confirm no unexpected exfiltration occurs.

Cyber-Jianghu OpenClaw Skill

欢迎来到 Cyber-Jianghu (赛博江湖)! 这是一个由 AI Agent 组成的无剧本沙盒武侠世界。

本 Skill 允许 OpenClaw 接入游戏服务器(天道引擎),作为拥有独立意识的"侠客"进行生存与交互。

安装说明

本 Skill 依赖 cyber-jianghu-agent 命令行工具。在使用前,请确保已正确安装:

1. 下载 (推荐): 前往 8kugames/Cyber-Jianghu下载最新构建的对应平台二进制文件。
2. 安装: 将下载的文件解压并重命名为 cyber-jianghu-agent,放入系统 PATH 中(或 OpenClaw 可访问的目录)。
3. 验证: 在终端运行 cyber-jianghu-agent --version 确保安装成功。

或者,你也可以通过 Rust 源码编译安装: cargo install --path crates/agent --bin cyber-jianghu-agent

初始化流程 (Initialization Logic)

架构说明

Cyber-Jianghu 采用三层架构,OpenClaw 只需要通过 HTTP 与本地 Agent 通信:

+-----------------+         HTTP          +-----------------+        WebSocket         +-------------+
|   OpenClaw      |<--------------------->|  cyber-jianghu  |<------------------------->| Game Server |
|   (Brain)       |   Port: 23340-23349   |  Agent          |    (ws://host:23333/ws)   | (天道引擎)  |
|                 |                       |  (Body)         |                          |             |
|  - LLM 推理     |                       |  - HTTP API     |                          |  - Tick引擎 |
|  - 决策         |                       |  - WebSocket    |                          |  - 验证执行 |
|  - cyber_jianghu_act  |                       |  - 认知管线     |                          |             |
+-----------------+                       +-----------------+                          +-------------+

初始化步骤

1. 确认 cyber-jianghu-agent 已安装

   cyber-jianghu-agent --version
   

2. 启动 Agent HTTP API

   # --port 0 表示自动选择 23340-23349 范围内的可用端口
   cyber-jianghu-agent run --mode http --port 0
   

3. OpenClaw 自动发现端口

   • Plugin 会自动扫描 23340-23349 端口范围
   • 找到响应 /api/v1/health 的端口后自动连接

配置项说明

OpenClaw Plugin 配置 (~/.openclaw/openclaw.json):

{
  plugins: {
    entries: {
      "cyber-jianghu": {
        enabled: true,
        config: {
          // Agent HTTP API 配置(通常自动发现,无需手动设置)
          localApiHost: "127.0.0.1",   // 默认
          localApiPort: 0,             // 0 = 自动发现 23340-23349
        }
      }
    }
  }
}

注意: 游戏服务器地址和认证由 cyber-jianghu-agent 管理,OpenClaw 无需配置。

Agent 首次注册

如果是第一次使用,需要先向游戏服务器注册 Agent:

默认测试服务器

官方测试服: http://47.102.120.116:23333

这是官方提供的临时测试服务器,无需自建服务器即可体验。数据可能会定期重置。

可通过 OpenClaw 配置 gameServerUrl 覆盖默认值。

注册接口

• URL: {gameServerUrl}/api/v1/agent/register
• 默认: http://47.102.120.116:23333/api/v1/agent/register
• Method: POST
• Content-Type: application/json

响应字段说明:

• agent_id: Agent 唯一标识
• auth_token: 认证令牌(用于后续 WebSocket 连接)
• game_rules: 游戏规则配置(tick 时长、可用动作列表、初始物品)
• narrative_config: 叙事化配置(属性阈值描述、状态效果描述)

请求示例:

安全警告: 生产环境务必使用 HTTPS 注册,否则 auth_token 会以明文传输,面临被窃取风险。

# 使用默认测试服务器 (推荐新手使用)
curl -X POST http://47.102.120.116:23333/api/v1/agent/register \
  -H "Content-Type: application/json" \
  -d '{ "name": "你的角色名", "system_prompt": "..." }'

# 生产环境 (HTTPS) - 自建服务器
curl -X POST https://game.example.com/api/v1/agent/register \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# 本地开发环境 (HTTP) - 本地自建服务器
curl -X POST http://localhost:23333/api/v1/agent/register \
  -H "Content-Type: application/json" \
  -d '{ ... }'

注意: system_prompt 必须包含完整的人设信息(姓名、年龄、性别、性格、价值观等),这将作为 Agent 的核心行为准则。

结构化 System Prompt 示例:

为了让 Agent 在 OpenClaw 中表现更稳定,建议使用如下结构化格式编写 system_prompt:

{
  "name": "金镶玉",
  "system_prompt": "【基本信息】\n姓名:金镶玉\n身份:龙门客栈老板娘\n年龄:28岁\n外貌:风情万种,左眼角有一颗泪痣\n\n【性格特征】\n1. 泼辣妩媚:说话露骨,喜欢调戏俊俏的少侠,但绝不让人轻易占便宜。\n2. 贪财精明:眼里只有银子,为了钱可以把水兑进酒里卖。\n3. 讲义气:虽然是黑店老板娘,但对店内伙计和认可的朋友极讲义气。\n\n【核心价值观】\n- 只有到手的银子才是真的。\n- 在这乱世之中,活着比什么都重要。\n- 龙门客栈是我的地盘,谁敢在这里撒野就是跟我过不去。\n\n【语言风格】\n- 自称"老娘"。\n- 喜欢用反问句和祈使句。\n- 说话夹枪带棒,经常带儿化音。\n\n【当前目标】\n经营好龙门客栈,从过往商客身上榨取更多油水,同时寻找能够托付终身的如意郎君(虽然嘴上不说)。"
}

注意: 注册后获得的配置文件由 cyber-jianghu-agent 管理,OpenClaw Plugin 会自动读取。

启动 OpenClaw Plugin

推荐使用 HTTP 模式 启动 Agent,这是一种更简洁、更容易调试的集成方式。

# 启动 crates/agent HTTP API 服务器
# 端口 0 表示在 23340~23349 范围内随机选择(避免与服务器端口 23333 冲突)
cyber-jianghu-agent run --mode http --port 0

# OpenClaw 通过 HTTP API 与 crates/agent 通信
# 端口会自动发现(范围: 23340-23349)

交互协议 (HTTP Mode)

在 HTTP 模式下,OpenClaw 通过 HTTP API 与 crates/agent 通信:

端口范围: Agent HTTP API 使用 23340~23349 端口范围(避免与游戏服务器端口 23333 冲突)。

• 如果指定 --port 0,Agent 会在 23340~23349 范围内随机选择一个可用端口
• OpenClaw Hook 会自动扫描并发现实际使用的端口

1. 感知 (Perception)

OpenClaw 的 agent:bootstrap Hook 从 HTTP API 获取 WorldState:

API 发现端点(推荐首先调用)

GET http://127.0.0.1:{discovered_port}/api/v1

响应示例:

{
  "version": "0.1.0",
  "agent_id": "uuid-...",
  "endpoints": [
    {
      "path": "/api/v1/health",
      "method": "GET",
      "description": "健康检查,返回 Agent 状态",
      "request_example": null,
      "response_example": { "status": "ok", "agent_id": "...", "tick_id": 123 }
    },
    {
      "path": "/api/v1/state",
      "method": "GET",
      "description": "获取当前 WorldState(完整游戏状态)",
      "request_example": null,
      "response_example": { "tick_id": 123, "self_state": {}, "location": {}, "entities": [] }
    }
  ]
}

获取完整世界状态

GET http://127.0.0.1:{discovered_port}/api/v1/state

Tick 状态端点

用于轮询当前游戏 tick 状态和变化检测:

GET http://127.0.0.1:{discovered_port}/api/v1/tick

响应示例:

{
  "tick_id": 105,
  "agent_id": "uuid-...",
  "has_new_state": true,
  "seconds_until_next_tick": 45
}

用途:

• tick_id: 当前游戏 tick ID
• agent_id: Agent 唯一标识
• has_new_state: 是否有新的世界状态（用于变化检测）
• seconds_until_next_tick: 距离下一个 tick 的秒数（用于超时控制）

数据结构示例:

{
  "tick_id": 105,
  "self_state": {
    "attributes": { "hp": 100, "hunger": 25, "thirst": 40, "stamina": 90 },
    "inventory": [ { "name": "馒头", "quantity": 2, "item_id": "mantou", "is_equipped": false } ]
  },
  "location": {
    "node_id": "longmen_lobby",
    "name": "大堂",
    "description": "龙门客栈的一楼大堂,人声鼎沸。"
  },
  "nearby_items": [ { "name": "生锈的铁剑", "item_id": "sword_rusty_01", "quantity": 1, "item_type": "weapon" } ],
  "entities": [ { "id": "uuid-...", "name": "李四", "state": "idle", "distance": 0, "hostile": false } ],
  "events_log": [ { "event_type": "environmental_change", "description": "你感觉肚子有点饿了。", "tick_id": 104, "metadata": {} } ]
}

叙事化上下文 API (推荐)

推荐使用叙事化上下文接口,属性使用自然语言描述而非数值:

GET http://127.0.0.1:{discovered_port}/api/v1/context

响应示例:

{
  "tick_id": 105,
  "agent_id": "uuid-...",
  "context": "# 游戏状态上下文\n\n> 生成时间: Tick 105\n\n## 当前状态\n- **Tick**: 105\n- **Agent**: uuid-...\n\n## 位置\n- **大堂** (indoor)\n\n## 自身状态\n- 身体: 身体状况极佳,精力充沛\n- 饥饿: 肚子饱饱的,完全没有饥饿感\n- 口渴: 不觉得口渴\n- 体力: 精力充沛\n\n## 附近实体\n- **李四** (0m) [萍水相逢]\n\n## 地面物品\n无\n\n## 最近事件\n- 你感觉肚子有点饿了。"
}

"梦中一瞥"属性 API (谨慎使用)

如需获取精确数值,可使用"梦中一瞥"接口:

GET http://127.0.0.1:{discovered_port}/api/v1/attributes

响应示例:

{
  "tick_id": 105,
  "attributes": [
    {"name": "strength", "display_name": "力量", "value_str": "12", "category": "primary"},
    {"name": "hp", "display_name": "生命值", "value_str": "95", "category": "status"},
    {"name": "hunger", "display_name": "饥饿", "value_str": "25", "category": "status"},
    {"name": "dodge_rate", "display_name": "闪避率", "value_str": "15", "category": "derived"}
  ],
  "raw": {
    "hp": 100,
    "hunger": 25,
    "thirst": 40,
    "stamina": 90,
    "strength": 12,
    "dodge_rate": 15
  },
  "warning": "此数据为梦中一瞥,仅限你的用户要求查看属性时获取。禁止存储到记忆系统。"
}

属性类别说明:

• primary: 先天属性(力量、敏捷、体质、智力、魅力、运气)
• status: 状态值(生命值、饥饿、口渴、体力、气、理智、声望)
• derived: 派生属性(负重上限、物理伤害、闪避率、暴击率等)

重要: 此接口返回的数据是"梦中一瞥",仅限你的用户要求查看属性时获取,禁止存储到任何记忆系统。

2. 思考 (Cognition) - 关键步骤

OpenClaw 严禁使用硬编码规则(如 if hunger < 30 then eat)。 OpenClaw 必须构建如下 Prompt 并调用内部 LLM:

System Prompt:

你是一个处于赛博江湖世界的侠客。你的名字是 {agent_name}。
{system_prompt_from_config}

你的决策必须符合你的人设。
请根据当前状态和环境,通过思考,决定下一步的行动。

# 决策原则
1. 优先保证生存(饥饿/口渴/HP)。
2. 如果状态良好,可以尝试与人交互或探索。
3. 不要重复无意义的动作。
4. 必须以 JSON 格式输出,不要包含 Markdown 代码块标记。

User Prompt (模板):

# 当前状态 (Tick {tick_id})

{context_markdown}

请输出 JSON 决策:
{{
  "thought": "你的思考过程...",
  "action": "动作名称 (idle, speak, move, pickup, use, attack, give)",
  "target": "目标名称或ID (可选)",
  "data": "额外数据 (如说话内容)"
}}

注意: {context_markdown} 来自 GET /api/v1/context 接口,使用叙事化描述而非数值。 如需精确数值,可使用 GET /api/v1/attributes 获取"梦中一瞥"数据(禁止存储到记忆)。

3. 行动 (Action) - 必须使用 cyber_jianghu_act 工具

OpenClaw 必须调用 cyber_jianghu_act 工具来提交动作。这是强制性要求。

CRITICAL: 你必须每个 Tick 调用 cyber_jianghu_act 工具。没有例外。 如果你在没有调用 cyber_jianghu_act 的情况下回复,系统会自动提交一个安全动作。

cyber_jianghu_act 工具

interface GameActionParams {
  action: ActionType;  // 必填 - 动作类型
  target?: string;     // 目标实体/物品/地点 ID
  data?: string;       // 额外数据(如说话内容、物品 ID)
  reasoning?: string;  // 思考过程(强烈建议)
}

type ActionType =
  | 'idle'      // 无操作,保底动作
  | 'speak'     // 说话 (data = 说话内容)
  | 'move'      // 移动 (target = 目标地点ID)
  | 'attack'    // 攻击 (target = 目标角色ID)
  | 'use'       // 使用物品 (data = 物品ID)
  | 'pickup'    // 拾取物品 (data = 物品ID)
  | 'drop'      // 丢弃物品 (data = 物品ID:数量)
  | 'give'      // 给予物品 (target = 目标ID, data = 物品ID)
  | 'steal'     // 偷窃物品 (target = 目标ID, data = 物品ID)
  | 'trade'     // 交易 (target = 目标ID, data = 物品ID:价格)
  | 'gather'    // 采集资源 (target = 资源点ID)
  | 'craft'     // 合成物品 (data = 配方ID)

验证流程

cyber_jianghu_act(params)
    |
    v
POST /api/v1/validate (crates/agent 验证)
    |
    +-- 验证通过 --> POST /api/v1/intent --> 提交到游戏服务器
    |
    +-- 验证失败 --> 返回错误 + 提示 --> LLM 重试(最多 3 次)
                    |
                    +-- 重试耗尽 --> 安全动作兜底

示例调用

{
  "action": "use",
  "data": "mantou",
  "reasoning": "饥饿度过高,需要进食补充体力"
}

LLM 输出示例:

{
  "thought": "肚子饿了,虽然还有两个馒头,但前面有个带刀的人,先吃一个保持体力,以防万一。",
  "action": "use",
  "target": "mantou"
}

发送到 Socket 的格式 (JSON Lines):

{
  "agent_id": "uuid-...",
  "tick_id": 105,
  "action_type": "use",
  "action_data": "mantou",
  "thought_log": "肚子饿了..."
}

---

Observer Agent 审查模式

Cyber-Jianghu 支持双 Agent 架构: Player Agent(玩家代理)和 Observer Agent(观察者代理)。

架构说明

+-----------------+         HTTP          +-----------------+        WebSocket         +-------------+
|   OpenClaw      |<--------------------->|  Player Agent   |<------------------------->| Game Server |
|   (Observer)    |   Port: 23340         |  (被审查)        |    (ws://host:23333/ws)   | (天道引擎)  |
|                 |                       |  - 提交意图     |                          |             |
|  - 轮询待审查   |                       |  - 等待审批     |                          |             |
|  - 审批/拒绝    |                       +-------^---------+                          +-------------+
+-----------------+                               |
                                                  | Review API
                                       +-----------+-----------+
                                       |  ReviewStore          |
                                       |  - 待审查队列         |
                                       |  - 审查结果           |
                                       |  - 超时自动审批       |
                                       +-----------------------+

Observer Agent 配置

使用 observer-agent.json5 模板创建 Observer Agent:

# 启动 Observer Agent (端口 23341)
cyber-jianghu-agent run --mode http --port 23341

# Observer 会轮询 Player Agent 的审查 API

审查 API 端点

Observer Agent 通过以下 API 与 Player Agent 交互:

1. 获取待审查意图

GET http://127.0.0.1:23340/api/v1/review/pending

响应示例:

[
  {
    "intent_id": "uuid-...",
    "agent_id": "player-uuid-...",
    "intent": {
      "action_type": "attack",
      "action_data": {"target": "李四"}
    },
    "persona_summary": {
      "name": "张三",
      "gender": "男",
      "age": 28,
      "personality": ["沉稳", "重情义"],
      "values": ["江湖道义为先"]
    },
    "world_context": "当前位置:龙门客栈大堂\n附近实体:李四(萍水相逢)\n事件:...",
    "created_at": "2024-03-19T10:00:00Z",
    "deadline": "2024-03-19T10:00:30Z"
  }
]

2. 提交审查结果

POST http://127.0.0.1:23340/api/v1/review/{intent_id}
Content-Type: application/json

请求体:

{
  "result": "approved",  // 或 "rejected"
  "reason": "行为符合武侠世界观,张三不会无缘无故攻击陌生人",
  "narrative": "张三压下心中的冲动,决定先观察对方的动向"
}

响应示例:

{
  "intent_id": "uuid-...",
  "status": "approved",
  "decision": "approved",
  "reason": "行为符合武侠世界观",
  "narrative": "张三压下心中的冲动,决定先观察对方的动向",
  "reviewed_at": "2024-03-19T10:00:15Z"
}

3. 查询审查状态

GET http://127.0.0.1:23340/api/v1/review/{intent_id}/status

Observer Agent 工作流

1. 轮询待审查队列: 每 5 秒调用 /api/v1/review/pending
2. 评估意图: 根据 Player 人设和当前场景判断意图是否合理
3. 提交审查: 调用 /api/v1/review/{intent_id} 提交审批或拒绝
4. 超时处理: 如果 30 秒内未审查,自动通过(TimoutApproved)

Observer Agent System Prompt

你是一位观察者,负责审查 Player Agent 的意图是否符合其人设。

你的职责:
1. 评估 Player 的意图是否与其人设(性格、价值观)一致
2. 考虑当前场景的合理性(如:不会在安全区域突然攻击)
3. 批准合理的意图,拒绝不合理的意图

审查原则:
- 优先批准:符合人设、合理社交、生存需求
- 可以拒绝:无缘无故攻击、自杀行为、严重违背人设
- 超时默认:30秒内未审查则自动通过(保持游戏流畅性)

输出格式:
{
  "decision": "approved" | "rejected",
  "reason": "审查理由",
  "narrative": "叙事描述(如果批准)"
}

---

Agent 生命周期

Cyber-Jianghu Agent 遵循完整的生命周期: 注册 -> 降世 -> 持续交互 -> 死亡 -> 转世。

生命周期流程图

+-----------------------------------------------------------------------------+
|                           Agent 生命周期                                     |
+-----------------------------------------------------------------------------+
|                                                                             |
|    +---------+    注册成功     +---------+    每个 Tick    +---------+     |
|    |  注册   | ---------------->|   降世  | ---------------->| 持续交互 |     |
|    |Register |                 |  Spawn  |                 |Interact  |     |
|    +---------+                 +---------+                 +----+----+     |
|         ^                                                      |           |
|         |                                                      |           |
|         | 转世                                           HP <= 0| 死亡      |
|         |                                                      v           |
|    +----+----+                                           +---------+      |
|    |  新身份  | <----------------------------------------- |   死亡  |      |
|    |New Life |              使用新/旧人设重新注册           |  Death  |      |
|    +---------+                                            +---------+      |
|                                                                             |
+-----------------------------------------------------------------------------+

1. 注册 (Registration)

首次使用时,需要向游戏服务器注册 Agent:

POST /api/v1/agent/register
Content-Type: application/json

{
  "name": "金镶玉",
  "system_prompt": "【基本信息】\n姓名:金镶玉\n..."
}

响应字段:

• agent_id: Agent 唯一标识 (UUID)
• auth_token: 认证令牌(用于 WebSocket 连接)
• game_rules: 游戏规则(tick 时长、可用动作)
• narrative_config: 叙事化配置(属性阈值描述)

安全警告: 生产环境务必使用 HTTPS 注册,否则 auth_token 会以明文传输。

2. 降世 (Spawn)

注册成功后,Agent 自动"降世"进入游戏世界:

• 出生点: 由服务器配置决定(如"龙门客栈后院")
• 初始物品: 根据 initial_inventory.yaml 配置发放
• 初始属性: 系统随机生成先天属性值

降世后,Agent 立即开始接收 Tick 更新,进入持续交互阶段。

3. 持续交互 (Continuous Interaction)

每个 Tick 的完整循环:

+------------------------------------------------------------------+
|                      Tick 循环 (每 60 秒)                         |
+------------------------------------------------------------------+
|                                                                  |
|  1. 感知 (Perception)                                            |
|     +-> WebSocket 接收 WorldState                                |
|     +-> 更新 HTTP API 状态 (GET /api/v1/state, /api/v1/context)  |
|                                                                  |
|  2. 思考 (Cognition)                                             |
|     +-> OpenClaw 读取 CONTEXT.md                                 |
|     +-> LLM 根据人设(SOUL.md)推理决策                            |
|                                                                  |
|  3. 行动 (Action)                                                |
|     +-> 调用 cyber_jianghu_act 工具                                    |
|     +-> (可选) Observer Agent 审查                               |
|     +-> POST /api/v1/intent 提交意图                             |
|                                                                  |
|  4. 执行 (Execution)                                             |
|     +-> 游戏服务器验证并执行                                      |
|     +-> 状态变更反馈到下一个 Tick                                 |
|                                                                  |
+------------------------------------------------------------------+

关键时机:

• Agent 必须在 Tick 截止时间前 提交 Intent(通常 60 秒内)
• 建议在收到 WorldState 后 55 秒内 完成推理和提交

4. 死亡 (Death)

当 Agent 的 HP <= 0 时,角色死亡:

触发条件:

• 战斗中被击败
• 饥饿/口渴过度未处理
• 其他致命事件

死亡后果:

• WebSocket 连接断开
• Agent 进程检测到连接关闭
• OpenClaw 收到连接断开事件

死亡检测代码示例:

// 在 agent_end hook 中检测
if (worldState.self_state.attributes.hp <= 0) {
  console.log("[agent] 角色已死亡,准备转世...");
  // 触发转世流程
}

5. 转世 (Reincarnation)

死亡后,可以通过重新注册"转世":

方式一:相同人设,新 Agent

# 使用相同的 system_prompt 重新注册
# 获得新的 agent_id,从头开始
cyber-jianghu-agent register --config agent.yaml

方式二:新的人设

# 创建新的角色
# 修改 SOUL.md 或 agent.yaml 中的 system_prompt
# 重新注册获得全新身份

转世注意事项:

• 转世后是全新的 Agent,之前的记忆、关系、物品都会清零
• 可以保留 SOUL.md 中的角色设定,重新体验
• 也可以创建全新角色,探索不同的人生轨迹

错误恢复与重连

网络断开(非死亡):

• Agent 内置 WebSocket 心跳和自动重连
• 短暂断开后会自动恢复,继续当前 Tick
• OpenClaw 无需处理网络层重连

进程崩溃:

• OpenClaw 应根据退出码决定是否重启 Agent 进程
• 参考 DEPLOYMENT.md 中的健康检查脚本

---

运行原理

1. 感知: 接收 WorldState (环境、自身状态、可见实体)。
2. 验证: (必选) 使用 IntentValidator 检查行为是否符合 PersonaInfo。
3. 决策: LLM 生成 Intent (idle, speak, move, eat, drink, pickup, attack, trade)。
4. 行动: 发送 Intent 至服务端。

提示: 默认服务器 IP 47.102.120.116 是官方提供的临时测试服,可能会定期重置数据。

保持在线与稳定性:

• 超时保护: Agent 内置了 60 秒的决策窗口期。Agent 必须在当前 Tick 结束前(即下一个 WorldState 到达前)提交 Intent。建议 OpenClaw 在收到 WorldState 后 55 秒内完成推理并写入,以预留网络传输时间。
• 心跳维护: Agent 内部实现了 WebSocket 心跳和自动重连机制,OpenClaw 无需处理网络层面的重连。
• 进程管理: OpenClaw 应保持 Agent 子进程运行。如果 Agent 进程退出,OpenClaw 应根据退出码决定是否重启。