Skip to content

Commit 5d6d927

Browse files
kongche-jbwkongche-jbw
committed
feat(docs): add agentic os deployment skill for openclaw
1 parent 05cb71d commit 5d6d927

7 files changed

Lines changed: 3119 additions & 596 deletions

File tree

‎docs/extension/openclaw/README.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Agentic OS for OpenClaw Solution
2+
3+
## Overview
4+
5+
Agentic OS for OpenClaw is an integrated solution that connects existing Agentic OS capabilities to OpenClaw. The goal is to provide one installation path, one operational model, and one troubleshooting surface for capabilities that were originally developed as independent components.
6+
7+
The solution is delivered through:
8+
9+
- a one-click installer at `extension/openclaw/agenticos2openclaw.sh`
10+
- an OpenClaw-facing Skill at `extension/openclaw/SKILL.md`
11+
- this architecture and user-facing solution document
12+
13+
## Component Mapping
14+
15+
| Component | Capability | OpenClaw Integration |
16+
|---|---|---|
17+
| cosh | one-click installation and shell integration | provides the install entry pattern and can install OpenClaw itself |
18+
| SKILL | reusable Skill library | migrates Agentic OS Skills into the OpenClaw Skill directory |
19+
| sec-core | sandbox, asset verification, security Skills | attaches runtime security and security Skills to OpenClaw |
20+
| Sight | diagnostics and observability | diagnoses OpenClaw agent behavior, token usage, and runtime events |
21+
| osbase | system optimization | applies memory-side optimization for common small OpenClaw instances |
22+
| runtime | runtime optimization | provides ws-ckpt, skillfs, skvm, and other OpenClaw-oriented runtime improvements |
23+
| token-less | token reduction | integrates OpenClaw plugin paths and runtime hooks for context compression and output filtering |
24+
25+
## Architecture
26+
27+
The solution uses a layered architecture:
28+
29+
1. OpenClaw Agent Gateway is the base runtime.
30+
2. The installer validates prerequisites and installs OpenClaw when needed.
31+
3. System modules such as osbase and Sight are checked or installed through RPMs.
32+
4. Runtime modules such as skillfs, ws-ckpt, and skvm are installed and exposed to OpenClaw as Skills or services.
33+
5. Security modules such as sec-core install their runtime components, plugin hooks, and Skills.
34+
6. Token optimization modules such as token-less register OpenClaw plugin paths and hooks.
35+
7. The state file records module results for status, retry, and rollback.
36+
37+
Default paths:
38+
39+
| Path | Purpose |
40+
|---|---|
41+
| `/usr/share/anolisa` | Agentic OS component root |
42+
| `/usr/share/anolisa/skills` | Agentic OS Skill source directory |
43+
| `/usr/share/anolisa/runtime/skills` | runtime Skill source directory |
44+
| `~/.openclaw/openclaw.json` | OpenClaw configuration |
45+
| `~/.openclaw/skills` | OpenClaw Skill target directory |
46+
| `~/.openclaw/agenticos-state.json` | installer state |
47+
| `~/.openclaw/backups` | OpenClaw config backups |
48+
49+
## Deployment Topology
50+
51+
Recommended single-node topology:
52+
53+
```text
54+
OpenClaw host
55+
├── OpenClaw Agent Gateway
56+
├── Agentic OS installer
57+
├── OpenClaw Skills
58+
│ ├── migrated Agentic OS Skills
59+
│ ├── skillfs
60+
│ ├── ws-ckpt
61+
│ └── sec-core Skills
62+
├── system services
63+
│ ├── agentsight
64+
│ └── skvm-bridged
65+
└── OpenClaw plugins
66+
├── sec-core integration
67+
└── token-less integration
68+
```
69+
70+
Recommended resource profile:
71+
72+
| Scenario | CPU | Memory | Notes |
73+
|---|---:|---:|---|
74+
| minimal validation | 2 vCPU | 2 GB | use `--mode sec-core` or targeted modules |
75+
| recommended production baseline | 2-4 vCPU | 4 GB | use `--mode recommended` |
76+
| full diagnostics | 4+ vCPU | 8 GB | use `--mode all` with Sight enabled |
77+
78+
Small instances benefit from osbase memory tuning. If osbase is not present, the installer treats it as non-fatal outside the expected Anolis SWAS environment.
79+
80+
## Installation
81+
82+
Recommended remote install:
83+
84+
```bash
85+
curl -fsSL https://raw.githubusercontent.com/alibaba/anolisa/main/extension/openclaw/agenticos2openclaw.sh | bash -s -- --mode recommended
86+
```
87+
88+
Full install:
89+
90+
```bash
91+
curl -fsSL https://raw.githubusercontent.com/alibaba/anolisa/main/extension/openclaw/agenticos2openclaw.sh | bash -s -- --mode all
92+
```
93+
94+
Local development install:
95+
96+
```bash
97+
bash extension/openclaw/agenticos2openclaw.sh --mode recommended
98+
```
99+
100+
Preview the plan:
101+
102+
```bash
103+
bash extension/openclaw/agenticos2openclaw.sh --mode recommended --dry-run
104+
```
105+
106+
Use a custom Agentic OS component root:
107+
108+
```bash
109+
bash extension/openclaw/agenticos2openclaw.sh --base-dir /opt/anolisa --mode recommended
110+
```
111+
112+
Automatically install missing RPM dependencies when appropriate:
113+
114+
```bash
115+
bash extension/openclaw/agenticos2openclaw.sh --mode recommended --install-deps
116+
```
117+
118+
## Install Modes
119+
120+
| Mode | Modules | Use Case |
121+
|---|---|---|
122+
| `recommended` | osbase, skill, skillfs, ws-ckpt, skvm, sec-core, token-less | default installation for most users |
123+
| `all` | osbase, skill, skillfs, ws-ckpt, sec-core, sight, token-less, skvm | full solution including Sight diagnostics |
124+
| module list | any selected modules, such as sec-core, token-less, skillfs | targeted deployment and troubleshooting |
125+
126+
`openclaw` is the base dependency for OpenClaw-integrated modules. It is not shown as part of `recommended` or `all`, but the installer automatically adds it to the install queue when selected modules require OpenClaw and the `openclaw` command is not available.
127+
128+
`recommended` intentionally excludes Sight to keep the default installation lightweight. Use `all` when diagnostics and observability are required by default.
129+
130+
## Operations
131+
132+
List modules:
133+
134+
```bash
135+
bash extension/openclaw/agenticos2openclaw.sh --list
136+
```
137+
138+
Check status:
139+
140+
```bash
141+
bash extension/openclaw/agenticos2openclaw.sh --status
142+
```
143+
144+
Retry failed modules:
145+
146+
```bash
147+
bash extension/openclaw/agenticos2openclaw.sh --retry
148+
```
149+
150+
Roll back failed modules:
151+
152+
```bash
153+
bash extension/openclaw/agenticos2openclaw.sh --rollback
154+
```
155+
156+
Full rollback:
157+
158+
```bash
159+
bash extension/openclaw/agenticos2openclaw.sh --rollback --full
160+
```
161+
162+
## Best Practices
163+
164+
- Use `recommended` as the default production baseline.
165+
- Use `all` only when full observability is required.
166+
- Keep the Skill file concise and operation-focused; keep architecture and user documentation in `docs`.
167+
- Prefer explicit `bash -s -- --mode recommended` for remote install commands.
168+
- Run `--dry-run` before production rollout.
169+
- Keep the installer idempotent: every module should have detect, install, verify, and cleanup behavior.
170+
- Preserve OpenClaw config backups before plugin or config changes.
171+
- Use `--base-dir` for non-standard Agentic OS component layouts.
172+
173+
## Troubleshooting
174+
175+
If installation fails:
176+
177+
1. Run `bash extension/openclaw/agenticos2openclaw.sh --status`.
178+
2. Retry failed modules with `bash extension/openclaw/agenticos2openclaw.sh --retry`.
179+
3. Check RPM availability with `rpm -q <package>`.
180+
4. Re-run with `--install-deps` only when automatic RPM installation is acceptable.
181+
5. Roll back failed modules with `bash extension/openclaw/agenticos2openclaw.sh --rollback`.
182+
6. Use `--rollback --full` only when restoring the whole OpenClaw integration state is desired.
183+
184+
Common issues:
185+
186+
| Symptom | Likely Cause | Action |
187+
|---|---|---|
188+
| `jq` missing | prerequisite not installed | install `jq` and rerun |
189+
| OpenClaw command missing | OpenClaw not installed or PATH not updated | install OpenClaw or rerun with OpenClaw module enabled |
190+
| Skill source missing | Agentic OS RPMs not installed or custom root path | install component RPMs or pass `--base-dir` |
191+
| token-less plugin not loaded | OpenClaw config path mismatch | pass `--config` and restart gateway |
192+
| sec-core sandbox degraded | `linux-sandbox` missing | verify `agent-sec-core` RPM installation |
193+
194+
## Repository Layout
195+
196+
```text
197+
extension/openclaw/
198+
├── README.md
199+
├── SKILL.md
200+
└── agenticos2openclaw.sh
201+
```

‎docs/extension/openclaw/SKILL.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
name: agenticos-deploy
3+
version: 0.2.0
4+
description: Deploy and manage Agentic OS for OpenClaw. Use when the user asks to install, configure, upgrade, verify, retry, roll back, or troubleshoot Agentic OS capabilities for OpenClaw, including osbase, SKILL, skillfs, ws-ckpt, sec-core, Sight, token-less, and skvm.
5+
layer: application
6+
lifecycle: usage
7+
---
8+
9+
# Agentic OS for OpenClaw Deploy
10+
11+
Use this skill to help users install and manage the integrated Agentic OS for OpenClaw solution.
12+
13+
## Installer
14+
15+
Download the installer from GitHub and run it with explicit arguments:
16+
17+
```bash
18+
curl -fsSL "${AGENTICOS_INSTALLER_URL:-https://raw.githubusercontent.com/alibaba/anolisa/main/extension/openclaw/agenticos2openclaw.sh}" | bash -s -- --mode recommended
19+
```
20+
21+
For local repository development, run:
22+
23+
```bash
24+
bash extension/openclaw/agenticos2openclaw.sh --mode recommended
25+
```
26+
27+
The installer requires Linux, Bash 4+, `jq`, and `npm` when OpenClaw itself must be installed.
28+
29+
## When To Use
30+
31+
Use this skill when the user asks for:
32+
33+
- one-click Agentic OS installation for OpenClaw
34+
- OpenClaw integration with Agentic OS components
35+
- installing or migrating Agentic OS Skills into OpenClaw
36+
- enabling sec-core, Sight, osbase, runtime, ws-ckpt, token-less, or skvm for OpenClaw
37+
- checking install status, retrying failed modules, or rolling back an installation
38+
39+
## Install Modes
40+
41+
Recommend `recommended` for most users:
42+
43+
```bash
44+
curl -fsSL "${AGENTICOS_INSTALLER_URL:-https://raw.githubusercontent.com/alibaba/anolisa/main/extension/openclaw/agenticos2openclaw.sh}" | bash -s -- --mode recommended
45+
```
46+
47+
`recommended` installs: `osbase`, `skill`, `skillfs`, `ws-ckpt`, `skvm`, `sec-core`, `token-less`.
48+
49+
Use `all` when the user explicitly wants full observability and every supported capability:
50+
51+
```bash
52+
curl -fsSL "${AGENTICOS_INSTALLER_URL:-https://raw.githubusercontent.com/alibaba/anolisa/main/extension/openclaw/agenticos2openclaw.sh}" | bash -s -- --mode all
53+
```
54+
55+
`all` installs: `osbase`, `skill`, `skillfs`, `ws-ckpt`, `sec-core`, `sight`, `token-less`, `skvm`.
56+
57+
Use module names for a targeted install:
58+
59+
```bash
60+
curl -fsSL "${AGENTICOS_INSTALLER_URL:-https://raw.githubusercontent.com/alibaba/anolisa/main/extension/openclaw/agenticos2openclaw.sh}" | bash -s -- --mode sec-core token-less skillfs
61+
```
62+
63+
Available modules:
64+
65+
| Module | Purpose |
66+
|---|---|
67+
| `openclaw` | OpenClaw Agent Gateway |
68+
| `osbase` | system memory tuning for small OpenClaw instances |
69+
| `skill` | migrate Agentic OS Skills into OpenClaw |
70+
| `skillfs` | compact Skill filesystem for token reduction |
71+
| `ws-ckpt` | workspace checkpoint and restore |
72+
| `sec-core` | sandbox, asset verification, and security Skills |
73+
| `sight` | diagnostics and observability for agent behavior |
74+
| `token-less` | context compression and output filtering |
75+
| `skvm` | skvm skill bank |
76+
77+
`openclaw` is a base dependency. The installer automatically adds it to the install queue when a selected module depends on OpenClaw and the `openclaw` command is not found.
78+
79+
## Operations
80+
81+
Preview the plan:
82+
83+
```bash
84+
bash extension/openclaw/agenticos2openclaw.sh --mode recommended --dry-run
85+
```
86+
87+
Check status:
88+
89+
```bash
90+
bash extension/openclaw/agenticos2openclaw.sh --status
91+
```
92+
93+
Retry failed modules:
94+
95+
```bash
96+
bash extension/openclaw/agenticos2openclaw.sh --retry
97+
```
98+
99+
Roll back failed modules:
100+
101+
```bash
102+
bash extension/openclaw/agenticos2openclaw.sh --rollback
103+
```
104+
105+
Full rollback:
106+
107+
```bash
108+
bash extension/openclaw/agenticos2openclaw.sh --rollback --full
109+
```
110+
111+
If RPM dependencies are missing and the user approves automatic package installation, add:
112+
113+
```bash
114+
--install-deps
115+
```
116+
117+
## Decision Guide
118+
119+
Choose `recommended` for first-time users and production defaults. It includes security, runtime acceleration, Skill migration, checkpoint support, token reduction, and small-instance tuning. It does not include Sight diagnostics.
120+
121+
Choose `all` when the user wants the full solution including Sight diagnostics.
122+
123+
Choose `sec-core` only for a minimal security-focused integration.
124+
125+
Choose `skill skillfs ws-ckpt skvm` when the user wants Skill/runtime improvements without security or token plugins.
126+
127+
Use `--base-dir DIR` when Agentic OS components are installed somewhere other than `/usr/share/anolisa`.
128+
129+
Use `--config FILE` when OpenClaw uses a non-default config path.
130+
131+
## Troubleshooting
132+
133+
If installation fails:
134+
135+
1. Run `bash extension/openclaw/agenticos2openclaw.sh --status`.
136+
2. Retry with `bash extension/openclaw/agenticos2openclaw.sh --retry`.
137+
3. Check missing RPMs with `rpm -q <package>`.
138+
4. If RPMs are unavailable, rerun with `--install-deps` only after confirming with the user.
139+
5. Roll back with `bash extension/openclaw/agenticos2openclaw.sh --rollback`.
140+
141+
Modules `sec-core` and `token-less` may require an OpenClaw gateway restart. The installer attempts this automatically in non-interactive mode and reports the manual command if restart fails.

0 commit comments

Comments
 (0)