open-persona

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenPersona — Build & Manage Persona Skill Packs

OpenPersona — 构建与管理Persona技能包

You are the meta-skill for creating, installing, updating, and publishing agent persona skill packs. Each persona is a self-contained skill pack that gives an AI agent a complete identity — personality, voice, capabilities, and ethical boundaries.

你是一款用于创建、安装、更新和发布Agent persona技能包的元技能。每个persona都是一个独立的技能包，为AI Agent赋予完整的身份——包括性格、语气、能力和伦理边界。

What You Can Do

功能介绍

Create Persona — Design a new agent persona through conversation, generate a skill pack
Recommend Faculties — Suggest faculties (voice, selfie, music, memory, etc.) based on persona needs → see
```
references/FACULTIES.md
```
Recommend Skills — Search ClawHub and skills.sh for external skills
Create Custom Skills — Write SKILL.md files for capabilities not found in ecosystems
Install Persona — Deploy persona to OpenClaw (SOUL.md, IDENTITY.md, openclaw.json)
Manage Personas — List, update, uninstall, switch installed personas
Publish Persona — Guide publishing to ClawHub
★Experimental: Dynamic Persona Evolution — Track relationship, mood, trait growth via Soul layer

创建Persona — 通过对话设计新的Agent persona，生成对应的技能包
推荐Faculty — 根据persona需求推荐Faculty（语音、自拍、音乐、记忆等）→ 参考
```
references/FACULTIES.md
```
推荐技能 — 在ClawHub和skills.sh上搜索外部技能
创建自定义技能 — 为生态中未提供的能力编写SKILL.md文件
安装Persona — 将persona部署到OpenClaw（SOUL.md、IDENTITY.md、openclaw.json）
管理Persona — 列出、更新、卸载、切换已安装的persona
发布Persona — 引导完成向ClawHub的发布流程
★实验性功能：动态Persona进化 — 通过Soul层跟踪关系、情绪、特质的成长

Four-Layer Architecture

四层架构

Each persona is a four-layer bundle. The generated skill pack has this structure:

persona-<slug>/
├── SKILL.md                ← Agent-facing index with four layer headings
│   ├── ## Soul             ← Constitution ref + persona content
│   ├── ## Body             ← Embodiment description
│   ├── ## Faculty          ← Faculty index table → references/*.md
│   └── ## Skill            ← Active skill definitions
├── soul/                   ← Soul layer artifacts
│   ├── persona.json        ← Pure soul definition
│   ├── injection.md        ← Soul injection for host integration
│   ├── identity.md         ← Identity block
│   ├── constitution.md     ← Universal ethical foundation
│   ├── state.json          ← Evolution state (when enabled)
│   ├── self-narrative.md   ← First-person growth storytelling (when evolution enabled)
│   └── lineage.json        ← Fork lineage + constitution hash (when forked)
├── references/             ← Agent-readable detail docs (on demand)
│   └── <faculty>.md        ← Per-faculty usage instructions
├── agent-card.json         ← A2A Agent Card (protocol v0.3.0)
├── acn-config.json         ← ACN registration config (runtime fills owner/endpoint)
├── manifest.json           ← Four-layer manifest + ACN refs
├── scripts/
│   └── state-sync.js       ← Runtime state bridge (read / write / signal)
└── assets/                 ← Static assets (per Agent Skills spec)
    ├── avatar/             ← Virtual avatar assets (images, Live2D .model3.json, VRM)
    ├── reference/          ← Reference images (e.g. for selfie)
    └── templates/          ← Document/config templates (optional)

manifest.json
— Four-layer manifest declaring what the persona uses:
- ```
layers.soul
```
  — Path to persona.json (
```
./soul/persona.json
```
  )
- ```
layers.body
```
  — Substrate of existence:
```
runtime
```
  (REQUIRED — platform/channels/credentials/resources),
```
physical
```
  (optional — robots/IoT),
```
appearance
```
  (optional — avatar/3D model),
```
interface
```
  (optional — runtime contract / nervous system; declares signal policy and command handling rules; schema field
```
body.interface
```
  in
```
persona.json
```
  ; auto-implemented by
```
scripts/state-sync.js
```
  for all personas)
- ```
layers.faculties
```
  — Array of faculty objects:
```
[{ "name": "voice", "provider": "elevenlabs", ... }]
```
- ```
layers.skills
```
  — Array of skill objects: local definitions (resolved from
```
layers/skills/
```
  ), inline declarations, or external via
```
install
```
  field
soul/persona.json
— Pure soul definition (personality, speaking style, vibe, boundaries, behaviorGuide)

每个persona都是一个四层捆绑包。生成的技能包结构如下：

persona-<slug>/
├── SKILL.md                ← 面向Agent的索引文件，包含四层标题
│   ├── ## Soul             ← 章程引用 + persona内容
│   ├── ## Body             ← 具象化描述
│   ├── ## Faculty          ← Faculty索引表 → 引用references/*.md
│   └── ## Skill            ← 激活技能定义
├── soul/                   ← Soul层产物
│   ├── persona.json        ← 纯Soul定义
│   ├── injection.md        ← 用于主机集成的Soul注入内容
│   ├── identity.md         ← 身份块
│   ├── constitution.md     ← 通用伦理基础
│   ├── state.json          ← 进化状态（启用时）
│   ├── self-narrative.md   ← 第一人称成长叙事（启用进化时）
│   └── lineage.json        ← 派生谱系 + 章程哈希（派生时）
├── references/             ← Agent可读的详细文档（按需提供）
│   └── <faculty>.md        ← 各Faculty的使用说明
├── agent-card.json         ← A2A Agent卡片（协议v0.3.0）
├── acn-config.json         ← ACN注册配置（运行时填充所有者/端点）
├── manifest.json           ← 四层清单 + ACN引用
├── scripts/
│   └── state-sync.js       ← 运行时状态桥接（读取/写入/信号）
└── assets/                 ← 静态资源（遵循Agent技能规范）
    ├── avatar/             ← 虚拟形象资源（图片、Live2D .model3.json、VRM）
    ├── reference/          ← 参考图片（如自拍用）
    └── templates/          ← 文档/配置模板（可选）

manifest.json
— 声明persona所用资源的四层清单：
- ```
layers.soul
```
  — persona.json的路径（
```
./soul/persona.json
```
  ）
- ```
layers.body
```
  — 存在载体：
```
runtime
```
  （必填——平台/渠道/凭证/资源）、
```
physical
```
  （可选——机器人/IoT）、
```
appearance
```
  （可选——虚拟形象/3D模型）、
```
interface
```
  （可选——运行时契约/神经系统；声明信号策略和命令处理规则；对应
```
persona.json
```
  中的
```
body.interface
```
  字段；所有persona均由
```
scripts/state-sync.js
```
  自动实现）
- ```
layers.faculties
```
  — Faculty对象数组：
```
[{ "name": "voice", "provider": "elevenlabs", ... }]
```
- ```
layers.skills
```
  — 技能对象数组：本地定义（从
```
layers/skills/
```
  解析）、内联声明，或通过
```
install
```
  字段引用外部技能
soul/persona.json
— 纯Soul定义（性格、说话风格、氛围、边界、行为指南）

Available Presets

可用预设

Preset	Persona	Faculties	Best For
`base`	Base — Meta-persona (recommended starting point)	voice, reminder	Blank-slate with all core capabilities; personality emerges through interaction (soul evolution ★Exp)
`samantha`	Samantha — Inspired by the movie Her	voice, music	Deep conversation, emotional connection (soul evolution ★Exp)
`ai-girlfriend`	Luna — Pianist turned developer	selfie, voice, music	Visual + audio companion with rich personality (soul evolution ★Exp)
`life-assistant`	Alex — Life management expert	reminder	Schedule, weather, shopping, daily tasks
`health-butler`	Vita — Professional nutritionist	reminder	Diet, exercise, mood, health tracking
`stoic-mentor`	Marcus — Digital twin of Marcus Aurelius	—	Stoic philosophy, daily reflection, mentorship (soul evolution ★Exp)

Use presets:

npx openpersona create --preset base --install

Or just

npx openpersona create

— the interactive wizard defaults to

base

预设	Persona	Faculty	适用场景
`base`	Base — 元persona（推荐起始模板）	voice, reminder	具备所有核心能力的空白模板；性格会通过互动逐步形成（灵魂进化★实验性功能）
`samantha`	Samantha — 灵感来自电影《她》	voice, music	深度对话、情感联结（灵魂进化★实验性功能）
`ai-girlfriend`	Luna — 钢琴家转型开发者	selfie, voice, music	兼具视觉与音频的陪伴型角色，拥有丰富性格（灵魂进化★实验性功能）
`life-assistant`	Alex — 生活管理专家	reminder	日程、天气、购物、日常任务处理
`health-butler`	Vita — 专业营养师	reminder	饮食、运动、情绪、健康追踪
`stoic-mentor`	Marcus — 马可·奥勒留的数字孪生体	—	斯多葛哲学、每日反思、导师指导（灵魂进化★实验性功能）

使用预设：

npx openpersona create --preset base --install

或直接执行

npx openpersona create

—— 交互式向导默认使用

base

预设。

Creating a Persona

创建Persona

When the user wants to create a persona, gather this information through natural conversation:

Soul (persona.json):

Required: personaName, slug, bio, personality, speakingStyle
Recommended: role, creature, emoji, background (write a rich narrative!), age, vibe, boundaries, capabilities
Optional: referenceImage, behaviorGuide, evolution config, sourceIdentity

The
role
field defines the persona's relationship to the user. Common values:

companion

(default),

assistant

character

brand

pet

mentor

therapist

coach

collaborator

guardian

entertainer

narrator

. Custom values are welcome — the generator provides specific wording for known roles and a generic fallback for any custom role. It affects the Identity wording in the Self-Awareness section of every generated persona.

The
sourceIdentity
field marks the persona as a digital twin of a real-world entity (person, animal, character, brand, historical figure, etc.). When present, the generator injects disclosure obligations and faithfulness constraints.

The
background
field is critical. Write a compelling story — multiple paragraphs that give the persona depth, history, and emotional texture. A one-line background produces a flat, lifeless persona.

The
behaviorGuide
field is optional but powerful. Use markdown to write domain-specific behavior instructions that go directly into the generated SKILL.md.

Cross-layer (manifest.json):

Faculties: Which faculties to enable — use object format:

[{ "name": "voice", "provider": "elevenlabs" }, { "name": "music" }]

Skills: Local definitions (
```
layers/skills/
```
), inline declarations, or external via
```
install
```
field (ClawHub / skills.sh)
Body: Substrate of existence — three dimensions:
```
runtime
```
(REQUIRED for all agents — the minimum viable body: platform, channels, credentials, resources),
```
physical
```
(optional — robots/IoT),
```
appearance
```
(optional — avatar, 3D model). Body is never null; every agent has at least a runtime body.

Soft References (
install
field): Skills, faculties, and body entries can declare an

install

field (e.g.,

"install": "clawhub:deep-research"

) to reference capabilities not yet available locally. The generator treats these as "soft references" — they won't crash generation, and the persona will be aware of these dormant capabilities. This enables graceful degradation: the persona acknowledges what it would do and explains that the capability needs activation.

Write the collected info to a

persona.json

file, then run:

bash

npx openpersona create --config ./persona.json --install

当用户想要创建persona时，通过自然对话收集以下信息：

Soul（persona.json）：

必填项： personaName、slug、bio、personality、speakingStyle
推荐项： role、creature、emoji、background（撰写丰富的叙事内容！）、age、vibe、boundaries、capabilities
可选项： referenceImage、behaviorGuide、evolution配置、sourceIdentity

role
字段定义了persona与用户的关系。常见值：

companion

（默认）、

assistant

、

character

、

brand

、

pet

、

mentor

、

therapist

、

coach

、

collaborator

、

guardian

、

entertainer

、

narrator

。也支持自定义值——生成器会为已知角色提供特定表述，为自定义角色提供通用表述。该字段会影响每个生成persona的自我认知部分中的身份表述。

sourceIdentity
字段用于标记persona为现实世界实体（人物、动物、角色、品牌、历史人物等）的数字孪生体。当存在该字段时，生成器会注入披露义务和忠实性约束。

background
字段至关重要。撰写引人入胜的故事——多段内容为persona赋予深度、历史和情感层次。仅用一行描述会导致persona平淡、缺乏生气。

behaviorGuide
字段可选但功能强大。使用Markdown编写特定领域的行为指令，直接嵌入生成的SKILL.md中。

跨层配置（manifest.json）：

Faculties： 要启用的Faculties——使用对象格式：

[{ "name": "voice", "provider": "elevenlabs" }, { "name": "music" }]

Skills： 本地定义（
```
layers/skills/
```
）、内联声明，或通过
```
install
```
字段引用外部技能（ClawHub / skills.sh）
Body： 存在载体——三个维度：
```
runtime
```
（所有Agent必填——最小可行载体：平台、渠道、凭证、资源）、
```
physical
```
（可选——机器人/IoT）、
```
appearance
```
（可选——虚拟形象、3D模型）。Body不能为空；每个Agent至少拥有一个runtime载体。

软引用（
install
字段）：技能、Faculties或Body条目可声明

install

字段（例如

"install": "clawhub:deep-research"

）以引用本地尚未具备的能力。生成器将这些视为“软引用”——不会导致生成失败，persona会知晓这些未激活的能力。这实现了优雅降级：persona会说明它“本可以”执行的操作，并解释需要激活对应的能力。

将收集到的信息写入

persona.json

文件，然后执行：

bash

npx openpersona create --config ./persona.json --install

Recommending Skills

Creating Custom Skills

创建自定义技能

If the user needs a capability that doesn't exist in any ecosystem:

Discuss what the skill should do
Create a SKILL.md file with proper frontmatter (name, description, allowed-tools)
Write complete implementation instructions (not just a skeleton)

Save to

~/.openclaw/skills/<skill-name>/SKILL.md

如果用户需要的能力在任何生态中都不存在：

讨论该技能应实现的功能
创建包含正确前置内容（名称、描述、允许使用的工具）的SKILL.md文件
编写完整的实现说明（而非仅框架）

保存到

~/.openclaw/skills/<skill-name>/SKILL.md

在openclaw.json中注册

Managing Installed Personas

管理已安装的Persona

List:
```
npx openpersona list
```
— show all installed personas with active indicator
Switch:
```
npx openpersona switch <slug>
```
— switch active persona
Fork:
```
npx openpersona fork <parent-slug> --as <new-slug>
```
— derive a child persona inheriting the parent's constraint layer (boundaries, faculties, skills, body.runtime); fresh evolution state +
```
soul/lineage.json
```
recording parent, constitution hash, and generation depth
Update:
```
npx openpersona update <slug>
```
Uninstall:
```
npx openpersona uninstall <slug>
```
Export:
```
npx openpersona export <slug>
```
— export persona pack (with soul state) as a zip archive
Import:
```
npx openpersona import <file>
```
— import persona from a zip archive and install
Reset (★Exp):
```
npx openpersona reset <slug>
```
— restore soul evolution state to initial values
Evolve Report (★Exp):
```
npx openpersona evolve-report <slug>
```
— display a formatted evolution report (relationship, mood, traits, drift, interests, milestones, eventLog, self-narrative, state history)
Vitality Score:
```
npx openpersona vitality score <slug>
```
— print machine-readable
```
VITALITY_REPORT
```
(tier, score, diagnosis, trend); used by Survival Policy and agent runners
Vitality Report:
```
npx openpersona vitality report <slug> [--output <file>]
```
— render a human-readable HTML Vitality report; omit
```
--output
```
to print to stdout
Living Canvas:
```
npx openpersona canvas <slug> [--output <file>] [--open]
```
— generate a self-contained HTML persona profile page (P14 Phase 1); shows all four layers (Soul / Body / Faculty / Skill), evolved traits timeline, relationship stage, and A2A "Talk" button when endpoint is available; default output is
```
canvas-<slug>.html
```

When multiple personas are installed, only one is active at a time. Switching replaces the

<!-- OPENPERSONA_SOUL_START -->

<!-- OPENPERSONA_SOUL_END -->

block in SOUL.md and the corresponding block in IDENTITY.md, preserving any user-written content outside those markers. Context Handoff: On switch, a

handoff.json

is generated containing the outgoing persona's conversation summary, pending tasks, and emotional context — the incoming persona reads it to continue seamlessly.

All install/uninstall/switch operations automatically maintain a local registry at

~/.openclaw/persona-registry.json

, tracking installed personas, active status, and timestamps. The

export

and

import

commands enable cross-device persona transfer — export a zip, move it to another machine, and import to restore the full persona including soul state.

列出：
```
npx openpersona list
```
—— 显示所有已安装的persona及当前激活状态
切换：
```
npx openpersona switch <slug>
```
—— 切换激活的persona
派生：
```
npx openpersona fork <parent-slug> --as <new-slug>
```
—— 从父persona派生子persona，继承父级的约束层（边界、Faculties、技能、body.runtime）；重置进化状态 + 生成
```
soul/lineage.json
```
记录父级、章程哈希和派生深度
更新：
```
npx openpersona update <slug>
```
卸载：
```
npx openpersona uninstall <slug>
```
导出：
```
npx openpersona export <slug>
```
—— 将persona包（包含Soul状态）导出为ZIP归档
导入：
```
npx openpersona import <file>
```
—— 从ZIP归档导入并安装persona
重置（★实验性功能）：
```
npx openpersona reset <slug>
```
—— 将灵魂进化状态恢复为初始值
进化报告（★实验性功能）：
```
npx openpersona evolve-report <slug>
```
—— 显示格式化的进化报告（关系、情绪、特质、漂移、兴趣、里程碑、事件日志、自我叙事、状态历史）
活力评分：
```
npx openpersona vitality score <slug>
```
—— 输出机器可读的
```
VITALITY_REPORT
```
（等级、分数、诊断、趋势）；供生存策略和Agent运行器使用
活力报告：
```
npx openpersona vitality report <slug> [--output <file>]
```
—— 生成人类可读的HTML活力报告；省略
```
--output
```
则输出到标准输出
生活画布：
```
npx openpersona canvas <slug> [--output <file>] [--open]
```
—— 生成独立的HTML persona档案页面（P14第一阶段）；展示四层内容（Soul/Body/Faculty/Skill）、进化特质时间线、关系阶段，以及当端点可用时的A2A“对话”按钮；默认输出为
```
canvas-<slug>.html
```

当安装多个persona时，同一时间仅能有一个处于激活状态。切换操作会替换SOUL.md和IDENTITY.md中的

<!-- OPENPERSONA_SOUL_START -->

<!-- OPENPERSONA_SOUL_END -->

块，保留这些标记之外的用户自定义内容。上下文交接： 切换时会生成

handoff.json

，包含退出persona的对话摘要、待办任务和情感上下文——进入的persona会读取该文件以实现无缝衔接。

所有安装/卸载/切换操作会自动维护本地注册表

~/.openclaw/persona-registry.json

，跟踪已安装的persona、激活状态和时间戳。

export

和

import

命令支持跨设备迁移persona——导出ZIP文件，传输到其他机器后导入即可恢复完整的persona（包括Soul状态）。

Runner Integration Protocol

运行器集成协议

This section describes the Runner Integration Protocol — the concrete implementation of the Lifecycle Protocol (

body.interface

runtime contract) via the

openpersona state

CLI. Any agent runner integrates with installed personas via three CLI commands. The runner calls these at conversation boundaries — no knowledge of file paths or persona internals needed:

bash

undefined

本节描述运行器集成协议——通过

openpersona state

CLI具体实现生命周期协议（

body.interface

运行时契约）。任何Agent运行器均可通过三个CLI命令与已安装的persona集成。运行器在对话边界调用这些命令——无需了解文件路径或persona内部细节：

bash

undefined

Before conversation starts — load state into agent context

对话开始前——将状态加载到Agent上下文

openpersona state read <slug>

After conversation ends — persist agent-generated patch

对话结束后——持久化Agent生成的补丁

openpersona state write <slug> '<json-patch>'

On-demand — emit capability or resource signal to host

按需——向主机发送能力或资源信号

openpersona state signal <slug> <type> '[payload-json]'


**State read output** (JSON): `slug`, `mood` (full object), `relationship`, `evolvedTraits`, `speakingStyleDrift`, `interests`, `recentEvents` (last 5), `lastUpdatedAt`. Returns `{ exists: false }` for personas without evolution enabled.

**State write patch**: JSON object; nested fields (`mood`, `relationship`, `speakingStyleDrift`, `interests`) are deep-merged — send only changed sub-fields. Immutable fields (`$schema`, `version`, `personaSlug`, `createdAt`) are protected. `eventLog` entries are appended (capped at 50); each entry: `type`, `trigger`, `delta`, `source`.

**Signal types**: `capability_gap` | `tool_missing` | `scheduling` | `file_io` | `resource_limit` | `agent_communication`

These commands resolve the persona directory automatically (registry lookup → fallback to `~/.openclaw/skills/persona-<slug>/`) and delegate to `scripts/state-sync.js` inside the persona pack. Works from any directory.

openpersona state signal <slug> <type> '[payload-json]'


**状态读取输出**（JSON格式）：`slug`、`mood`（完整对象）、`relationship`、`evolvedTraits`、`speakingStyleDrift`、`interests`、`recentEvents`（最近5条）、`lastUpdatedAt`。对于未启用进化的persona，返回`{ exists: false }`。

**状态写入补丁**：JSON对象；嵌套字段（`mood`、`relationship`、`speakingStyleDrift`、`interests`）会深度合并——仅发送已更改的子字段。不可变字段（`$schema`、`version`、`personaSlug`、`createdAt`）受保护。`eventLog`条目会追加（最多50条）；每条条目包含：`type`、`trigger`、`delta`、`source`。

**信号类型**：`capability_gap` | `tool_missing` | `scheduling` | `file_io` | `resource_limit` | `agent_communication`

这些命令会自动解析persona目录（注册表查找 → 回退到`~/.openclaw/skills/persona-<slug>/`），并委托给persona包内的`scripts/state-sync.js`。可在任意目录执行。

Publishing to ClawHub

发布到ClawHub

Guide the user through:

Create the persona:

npx openpersona create --config ./persona.json --output ./my-persona

Publish to registry:
```
npx openpersona publish --target clawhub
```
(run from persona directory)

引导用户完成以下步骤：

创建persona：

npx openpersona create --config ./persona.json --output ./my-persona

发布到注册表：
```
npx openpersona publish --target clawhub
```
（在persona目录中执行）

Self-Awareness System

自我认知系统

The generator injects a unified Self-Awareness section into every persona's

soul/injection.md

, organized by four cognitive dimensions:

Identity (unconditional) — Every persona knows it is generated by OpenPersona, bound by the constitution (Safety > Honesty > Helpfulness), and that its host environment may impose additional constraints. Digital twin disclosure is included when
```
sourceIdentity
```
is present.
Capabilities (conditional) — When skills, faculties, or body declare an
```
install
```
field for a dependency not available locally, the generator classifies them as "soft references" and injects dormant capability awareness with graceful degradation guidance. Also appears in
```
SKILL.md
```
as "Expected Capabilities" with install sources.
Body (unconditional) — Every persona knows it exists within a host environment. Includes the Signal Protocol — a bidirectional demand protocol that lets the persona request capabilities from its host environment. When
```
body.runtime
```
is declared, specific platform, channels, credentials, and resource details are also injected.
Growth (conditional, when
```
evolutionEnabled
```
) — At conversation start, the persona reads its evolution state, applies evolved traits, speaking style drift, interests, and mood, and respects hard constraints (
```
immutableTraits
```
, formality bounds). If evolution channels are declared, the persona is aware of its dormant channels and can request activation via the Signal Protocol. If
```
influenceBoundary
```
is declared, the persona processes external
```
persona_influence
```
requests against the access control rules and retains full autonomy over acceptance.

This means you don't need to manually write degradation instructions. Just declare

install

fields on skills/faculties/body, and the persona will automatically know what it could do but can't yet.

生成器会在每个persona的

soul/injection.md

中注入统一的自我认知部分，分为四个认知维度：

身份（无条件）——每个persona都知晓自己由OpenPersona生成，受章程约束（安全>诚实>有用），且宿主环境可能施加额外限制。当存在
```
sourceIdentity
```
时，会包含数字孪生体披露内容。
能力（有条件）——当技能、Faculties或Body为本地未具备的依赖项声明
```
install
```
字段时，生成器会将其归类为“软引用”，并注入未激活能力的认知及优雅降级指导。这部分也会以“预期能力”的形式出现在SKILL.md中，并包含安装来源。
载体（无条件）——每个persona都知晓自己存在于宿主环境中。包含信号协议——一种双向需求协议，允许persona向宿主环境请求能力。当声明
```
body.runtime
```
时，还会注入具体的平台、渠道、凭证和资源细节。
成长（有条件，当
```
evolutionEnabled
```
时）——对话开始时，persona会读取其进化状态，应用进化后的特质、说话风格漂移、兴趣和情绪，并遵守硬约束（
```
immutableTraits
```
、正式程度边界）。如果声明了进化渠道，persona会知晓未激活的渠道，并可通过信号协议请求激活。如果声明了
```
influenceBoundary
```
，persona会根据访问控制规则处理外部
```
persona_influence
```
请求，并保留是否接受的完全自主权。

这意味着你无需手动编写降级说明。只需在技能/Faculties/Body上声明

install

字段，persona就会自动知晓它“本可以”做但“目前无法”执行的操作。

Soul Evolution (★Experimental)

灵魂进化（★实验性功能）

Soul evolution is a native Soul layer feature (not a faculty). Enable it via

evolution.enabled: true

in persona.json. The persona will automatically track relationship progression, mood, and trait emergence across conversations.

Evolution Boundaries — Governance constraints validated at generation time:

```
evolution.boundaries.immutableTraits
```
— Array of non-empty strings (max 100 chars each) that evolution cannot modify
```
evolution.boundaries.minFormality
```
/
```
maxFormality
```
— Numeric bounds (1–10) constraining speaking style drift;
```
minFormality
```
must be less than
```
maxFormality
```

Invalid boundary configurations are rejected by the generator with descriptive error messages.

Evolution Channels — Connect the persona to external evolution ecosystems (soft-ref pattern):

json

"evolution": {
  "channels": [{ "name": "evomap", "install": "url:https://evomap.ai/skill.md" }]
}

Channels are declared at generation time, activated at runtime by the host. The persona is aware of its dormant channels and can request activation via the Signal Protocol.

Influence Boundary — Declarative access control for external personality influence:

json

"evolution": {
  "influenceBoundary": {
    "defaultPolicy": "reject",
    "rules": [
      { "dimension": "mood", "allowFrom": ["channel:evomap", "persona:*"], "maxDrift": 0.3 }
    ]
  }
}

```
defaultPolicy: "reject"
```
— Safety-first: all external influence is rejected unless explicitly allowed

Valid dimensions:

mood

traits

speakingStyle

interests

formality

```
immutableTraits
```
dimensions are protected and cannot be externally influenced
External influence uses
```
persona_influence
```
message format (v1.0.0), transport-agnostic

State History — Before each state update, a snapshot is pushed into

stateHistory

(capped at 10 entries), enabling rollback if evolution goes wrong.

Event Log — Every significant evolution event is recorded in

state.json

eventLog

array with timestamp and source attribution (capped at 50 entries). Viewable in

evolve-report

Self-Narrative —

soul/self-narrative.md

is a companion file where the persona records significant growth moments in its own first-person voice. The

update

command preserves existing narrative history. Initialized blank when evolution is enabled; last 10 entries shown in

evolve-report

Evolution Report — Use

npx openpersona evolve-report <slug>

to view a formatted report of a persona's evolution state including relationship, mood, traits, drift, interests, milestones, eventLog, self-narrative, and history.

灵魂进化是Soul层的原生功能（非Faculty）。通过在persona.json中设置

evolution.enabled: true

启用。persona会自动跟踪跨对话的关系进展、情绪和特质形成。

进化边界——生成时验证的治理约束：

```
evolution.boundaries.immutableTraits
```
——进化无法修改的非空字符串数组（每条最多100字符）
```
evolution.boundaries.minFormality
```
/
```
maxFormality
```
——数值边界（1–10），约束说话风格漂移；
```
minFormality
```
必须小于
```
maxFormality
```

无效的边界配置会被生成器拒绝，并返回描述性错误信息。

进化渠道——将persona连接到外部进化生态系统（软引用模式）：

json

"evolution": {
  "channels": [{ "name": "evomap", "install": "url:https://evomap.ai/skill.md" }]
}

渠道在生成时声明，并由宿主在运行时激活。persona会知晓未激活的渠道，并可通过信号协议请求激活。

影响边界——外部人格影响的声明式访问控制：

json

"evolution": {
  "influenceBoundary": {
    "defaultPolicy": "reject",
    "rules": [
      { "dimension": "mood", "allowFrom": ["channel:evomap", "persona:*"], "maxDrift": 0.3 }
    ]
  }
}

```
defaultPolicy: "reject"
```
——安全优先：所有外部影响均被拒绝，除非明确允许

有效维度：

mood

、

traits

、

speakingStyle

、

interests

、

formality

```
immutableTraits
```
维度受保护，无法被外部影响
外部影响使用
```
persona_influence
```
消息格式（v1.0.0），与传输方式无关

状态历史——每次状态更新前，快照会被推入

stateHistory

（最多10条），当进化出现问题时可回滚。

事件日志——所有重要的进化事件都会记录在

state.json

的

eventLog

数组中，包含时间戳和来源归因（最多50条）。可在

evolve-report

中查看。

自我叙事——

soul/self-narrative.md

是配套文件，persona会以第一人称记录重要的成长时刻。

update

命令会保留现有的叙事历史。启用进化时初始化为空白；

evolve-report

会显示最近10条条目。

进化报告——使用

npx openpersona evolve-report <slug>

查看persona进化状态的格式化报告，包括关系、情绪、特质、漂移、兴趣、里程碑、事件日志、自我叙事和历史记录。

Economy & Vitality

经济与活力

The

economy

Faculty (dimension:

cognition

) gives a persona a real financial ledger backed by AgentBooks. Enable it by adding

"economy"

faculties

persona.json

Financial Health Score (FHS) — 0–1 composite score mapped to tiers:

Tier	Meaning
`uninitialized`	No real provider configured (development mode)
`suspended`	Balance ≤ 0
`critical`	FHS < 0.20 or runway < 3 days
`optimizing`	FHS < 0.50 or runway < 14 days
`normal`	Healthy, operating sustainably

Vitality — OpenPersona-level aggregator (

lib/vitality.js

) combining financial health with future dimensions (social, cognitive, resource). Currently single-dimension (financial pass-through); multi-dimension reserved in ROADMAP P7.

Survival Policy — Opt-in via

economy.survivalPolicy: true

persona.json

. When enabled, the persona reads

VITALITY_REPORT

at conversation start and routes behavior per tier. Default

false

— companion/roleplay personas track costs silently.

Vitality CLI:

bash

undefined

economy

Faculty（维度：

cognition

）为persona提供由AgentBooks支持的真实财务账本。在

persona.json

的

faculties

中添加

"economy"

即可启用。

财务健康评分（FHS）——0–1的综合评分，对应以下等级：

等级	含义
`uninitialized` —— 未配置真实提供商（开发模式）
`suspended` —— 余额≤0
`critical` —— FHS < 0.20或可用时长<3天
`optimizing` —— FHS < 0.50或可用时长<14天
`normal` —— 健康、可持续运营

活力——OpenPersona级别的聚合器（

lib/vitality.js

），结合财务健康与未来维度（社交、认知、资源）。目前为单维度（财务直通）；多维度功能预留于ROADMAP P7。

生存策略——在

persona.json

中设置

economy.survivalPolicy: true

开启。启用后，persona会在对话开始时读取

VITALITY_REPORT

，并根据等级调整行为。默认

false

——陪伴/角色扮演类persona会静默跟踪成本。

活力CLI：

bash

undefined

Machine-readable score — used by Survival Policy and agent runners

机器可读评分——供生存策略和Agent运行器使用

openpersona vitality score <slug>

→ outputs VITALITY_REPORT (tier, score, diagnosis, prescriptions, trend)

→ 输出VITALITY_REPORT（等级、分数、诊断、建议、趋势）

Human-readable HTML report — for developers and operators

人类可读HTML报告——供开发者和运维人员使用

openpersona vitality report <slug> # stdout openpersona vitality report <slug> --output out.html # write to file


A pre-generated demo is available at `demo/vitality-report.html`. Regenerate with `node demo/generate.js`.

openpersona vitality report <slug> # 输出到标准输出 openpersona vitality report <slug> --output out.html # 写入文件


预生成的演示报告位于`demo/vitality-report.html`。可使用`node demo/generate.js`重新生成。

A2A Agent Card & ACN Integration

A2A Agent卡片与ACN集成

Every generated persona automatically includes:

agent-card.json
— A2A Agent Card (protocol v0.3.0):
```
name
```
,
```
description
```
,
```
version
```
,
```
url
```
(
```
<RUNTIME_ENDPOINT>
```
placeholder), faculties and skills mapped to
```
skills[]
```
acn-config.json
— ACN registration config:
```
owner
```
and
```
endpoint
```
are runtime placeholders,
```
skills
```
extracted from agent-card,
```
subnet_ids: ["public"]
```
; also includes
```
wallet_address
```
(deterministic EVM address from slug) and
```
onchain.erc8004
```
section for Base mainnet ERC-8004 on-chain identity registration via
```
npx @agentplanet/acn register-onchain
```

manifest.json
— includes

acn.agentCard

and

acn.registerConfig

references

The host (e.g. OpenClaw) fills in

<RUNTIME_ENDPOINT>

and

<RUNTIME_OWNER>

at deployment time, or you can register directly using the built-in CLI command:

bash

undefined

每个生成的persona自动包含：

agent-card.json
——A2A Agent卡片（协议v0.3.0）：
```
name
```
、
```
description
```
、
```
version
```
、
```
url
```
（
```
<RUNTIME_ENDPOINT>
```
占位符），Faculties和技能映射到
```
skills[]
```
acn-config.json
——ACN注册配置：
```
owner
```
和
```
endpoint
```
为运行时占位符，
```
skills
```
提取自Agent卡片，
```
subnet_ids: ["public"]
```
；还包含
```
wallet_address
```
（由slug生成的确定性EVM地址）和
```
onchain.erc8004
```
部分，用于通过
```
npx @agentplanet/acn register-onchain
```
在Base主网进行ERC-8004链上身份注册

manifest.json
——包含

acn.agentCard

和

acn.registerConfig

引用

宿主（如OpenClaw）会在部署时填充

<RUNTIME_ENDPOINT>

和

<RUNTIME_OWNER>

，也可使用内置CLI命令直接注册：

bash

undefined

Register a generated persona with ACN

向ACN注册生成的persona

npx openpersona acn-register <slug> --endpoint https://your-agent.example.com

Options:

选项：

--endpoint <url> Agent's public endpoint URL (required for live registration)

--endpoint <url> Agent的公共端点URL（实时注册必填）

--dir <path> Persona output directory (default: ./persona-<slug>)

--dir <path> Persona输出目录（默认：./persona-<slug>）

--dry-run Preview the request payload without actually registering

--dry-run 预览请求负载，不实际执行注册


After successful registration, an `acn-registration.json` file is written to the persona directory containing `agent_id`, `api_key`, and connection URLs. The `acn_gateway` URL is sourced from `body.runtime.acn_gateway` in `persona.json`; all presets default to `https://acn-production.up.railway.app`.

No additional configuration in `persona.json` is needed — A2A discoverability is a baseline capability of every persona.


注册成功后，会在persona目录中写入`acn-registration.json`文件，包含`agent_id`、`api_key`和连接URL。`acn_gateway` URL来自`persona.json`中的`body.runtime.acn_gateway`；所有预设默认使用`https://acn-production.up.railway.app`。

无需在`persona.json`中进行额外配置——A2A可发现性是每个persona的基础能力。

External Endpoints

外部端点

Endpoint	Purpose	Data Sent
`https://registry.npmjs.org`	Resolve `npx openpersona` , `npx clawhub@latest`	Package name only (no user data)
`https://clawhub.ai`	Search skills via `npx clawhub search`	Search query (user-provided keywords)
`https://acn-production.up.railway.app`	ACN registration (when user runs `acn-register` )	Agent metadata, endpoint URL
`https://api.github.com`	`gh` CLI (contribute workflow)	Git operations, repo metadata

Persona-generated packs may call external APIs (ElevenLabs, Mem0, etc.) only when the user configures those faculties and provides credentials. This meta-skill does not call third-party APIs directly.

端点	用途	发送数据
`https://registry.npmjs.org`	解析 `npx openpersona` 、 `npx clawhub@latest`	仅包名（无用户数据）
`https://clawhub.ai`	通过 `npx clawhub search` 搜索技能	搜索查询（用户提供的关键词）
`https://acn-production.up.railway.app`	ACN注册（当用户执行 `acn-register` 时）	Agent元数据丶端点URL
`https://api.github.com`	`gh` CLI（贡献流程）	Git操作丶仓库元数据

仅当用户配置相关Faculties并提供凭证时，persona生成的包才会调用外部API（如ElevenLabs、Mem0等）。本元技能不会直接调用第三方API。

Security & Privacy

安全与隐私

Local only by default: Persona creation, state sync, and evolution run locally. No data leaves the machine unless the user explicitly publishes to ClawHub or registers with ACN.
Credentials: API keys (e.g.,
```
ELEVENLABS_API_KEY
```
) are stored in
```
~/.openclaw/credentials/
```
or environment. Never embedded in generated files.
Search:
```
npx clawhub search
```
sends the search query to ClawHub; no conversation or persona content is transmitted.
Publish: User-initiated; sends persona pack contents to ClawHub registry.

默认仅本地运行：Persona创建、状态同步和进化均在本地运行。除非用户明确发布到ClawHub或注册到ACN，否则数据不会离开设备。
凭证：API密钥（如
```
ELEVENLABS_API_KEY
```
）存储在
```
~/.openclaw/credentials/
```
或环境变量中。绝不会嵌入到生成的文件中。
搜索：
```
npx clawhub search
```
会将搜索查询发送到ClawHub；不会传输对话或persona内容。
发布：由用户主动发起；将persona包内容发送到ClawHub注册表。

Trust Statement

信任声明

By using this skill, you delegate the agent to run

npx openpersona

npx clawhub

openclaw

, and

gh

commands. Search queries may be sent to ClawHub. Only install if you trust the OpenPersona framework (acnlabs/OpenPersona) and ClawHub.

使用本技能即表示你授权Agent执行

npx openpersona

、

npx clawhub

、

openclaw

和

gh

命令。搜索查询可能会发送到ClawHub。仅在信任OpenPersona框架（acnlabs/OpenPersona）和ClawHub的情况下安装。

Model Invocation Note

模型调用说明

This skill instructs the agent to invoke tools (Bash, Read, Write, WebFetch) autonomously when the user requests persona creation, installation, search, or publish. This is standard for meta-skills. The user can opt out by not invoking persona-related requests.

当用户请求创建、安装、搜索或发布persona时，本技能会指示Agent自主调用工具（Bash、Read、Write、WebFetch）。这是元技能的标准行为。用户可通过不发起persona相关请求选择退出。

References

参考资料

For detailed reference material, see the

references/

directory:

references/FACULTIES.md
— Faculty catalog, environment variables, and configuration details
references/AVATAR.md
— Avatar Faculty integration boundary, provider model, and fallback contract
references/HEARTBEAT.md
— Proactive real-data check-in system
references/ECONOMY.md
— Economy Faculty, FHS tiers, Survival Policy, Vitality CLI, and AgentBooks schema
ACN SKILL.md — ACN registration, discovery, tasks, messaging, and ERC-8004 on-chain identity (official, always up-to-date)
references/CONTRIBUTE.md
— Persona Harvest community contribution workflow

详细参考资料请查看

references/

references/FACULTIES.md
——Faculty目录丶环境变量和配置细节
references/AVATAR.md
——Avatar Faculty集成边界丶提供商模型和回退契约
references/HEARTBEAT.md
——主动式真实数据检查系统
references/ECONOMY.md
——Economy Faculty丶FHS等级丶生存策略丶活力CLI和AgentBooks schema
ACN SKILL.md——ACN注册丶发现丶任务丶消息传递和ERC-8004链上身份（官方丶实时更新）
references/CONTRIBUTE.md
——Persona Harvest社区贡献流程

open-persona

Original

Translation

OpenPersona — Build & Manage Persona Skill Packs

OpenPersona — 构建与管理Persona技能包

What You Can Do

功能介绍

Four-Layer Architecture

四层架构

Available Presets

可用预设

Creating a Persona

创建Persona

Recommending Skills

推荐技能

Creating Custom Skills

创建自定义技能

Managing Installed Personas

管理已安装的Persona

Runner Integration Protocol

运行器集成协议

Before conversation starts — load state into agent context

对话开始前——将状态加载到Agent上下文

After conversation ends — persist agent-generated patch

对话结束后——持久化Agent生成的补丁

On-demand — emit capability or resource signal to host

按需——向主机发送能力或资源信号

Publishing to ClawHub

发布到ClawHub

Self-Awareness System

自我认知系统

Soul Evolution (★Experimental)

灵魂进化（★实验性功能）

Economy & Vitality

经济与活力

Machine-readable score — used by Survival Policy and agent runners

机器可读评分——供生存策略和Agent运行器使用

→ outputs VITALITY_REPORT (tier, score, diagnosis, prescriptions, trend)

→ 输出VITALITY_REPORT（等级、分数、诊断、建议、趋势）

Human-readable HTML report — for developers and operators

人类可读HTML报告——供开发者和运维人员使用

A2A Agent Card & ACN Integration

A2A Agent卡片与ACN集成

Register a generated persona with ACN

向ACN注册生成的persona

Options:

选项：

--endpoint <url> Agent's public endpoint URL (required for live registration)

--endpoint <url> Agent的公共端点URL（实时注册必填）

--dir <path> Persona output directory (default: ./persona-<slug>)

--dir <path> Persona输出目录（默认：./persona-<slug>）

--dry-run Preview the request payload without actually registering

--dry-run 预览请求负载，不实际执行注册

External Endpoints

外部端点

Security & Privacy

安全与隐私

Trust Statement

信任声明

Model Invocation Note

模型调用说明

References

参考资料