ClawDSH

Name: ClawDSH
Rating: 3.5 (1 reviews)
Author: Fatemoisted

By Fatemoisted 👁 12 views ▲ 0 votes

OpenClaw capabilities, rebuilt as composable dsh plugins.

Homepage GitHub

Install

npm install
pnpm

Configuration Example

DEEPSEEK_API_KEY: "<your-deepseek-key>"
ARK_API_KEY: "<your-ark-key>"

README

<!-- ═══════════════ ClawDSH PUBLIC LANDING START ═══════════════ -->

# ClawDSH

English | [中文](README.zh.md)

<p align="center"><img src="packages/openclaw/preset-openclaw/brand/clawdsh-lockup.svg" alt="ClawDSH — Tidal Claw whale mark" width="520"></p>

> **OpenClaw capabilities, rebuilt as composable dsh plugins.**

ClawDSH is a local personal-assistant product built on the DeepSeek Harness (`dsh`) plugin runtime. It preserves the native Harness application for advanced use while adding an opinionated product profile, memory, skills, automation, privacy-limited activity records, and an optional OpenClaw communication plane.

ClawDSH is an independent community project. It is built on DeepSeek Harness and interoperates with OpenClaw, but it is not endorsed by or affiliated with either project. This release is `0.1.0-rc.1`: use the `next` npm tag, expect release-candidate changes, and do not treat it as a stable compatibility promise.

## How the projects relate

| Project | Role in ClawDSH | What remains independently owned |
|---|---|---|
| ClawDSH | Product profile, owned plugins, managed installer, `/clawdsh/` UI, and the Tidal Claw brand | ClawDSH settings, release lifecycle, and community support |
| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | Cordis-based agent runtime, model/tool/session services, and the native Web application | Upstream source, native UI, and the `dsh` architecture |
| [OpenClaw](https://github.com/openclaw/openclaw) | Optional communication-plane runtime and platform account owner | Platform adapters, accounts, credentials, policy, and state |

The ClawDSH repository tracks DeepSeek Harness as the `upstream` Git remote. The [Harness context and reuse map](docs/specs/context-map.md) explains the reused dsh capability seams; the [roadmap](docs/specs/roadmap.md) and [parity matrix](docs/matrix/parity.md) describe ClawDSH-owned work.

## Features and safe defaults

| Feature | User-visible behavior | Clean-install state |
|---|---|---|
| ClawDSH mode | New product sessions use the `clawdsh` preset and open in the native dsh conversation UI | Enabled |
| Soul | Adds the personal-assistant prompt layer; edits apply to new sessions | Enabled |
| Memory and Ark recall | Stores Markdown memory under `$DSH_HOME/memory`; Ark embeddings add optional semantic recall | Memory enabled; Ark key optional until an embedding call |
| Skills Hub | Loads workspace skills and the compatible `~/.clawdbot/skills` directory | Enabled |
| Automation | Runs scheduled agent work in dedicated sessions | Disabled |
| Activity | Explains selected Soul, Memory, Skill, Channel, and Automation facts without copying secrets or raw platform identities | Enabled and non-blocking |
| OpenClaw Gateway | Provides the locked external communication plane after explicit installation and configuration | Disabled |
| Harness Advanced | Keeps the unmodified upstream application at `/` for presets, raw trajectory, and advanced controls | Available |

The Channel catalog is evidence, not a support claim. Telegram, Feishu, Discord, and other catalog entries are not declared installable, certified, enabled, or ready merely because they appear in the UI. ClawDSH ships no direct platform adapter.

## Quick start

### Requirements

- Node.js `22.19.x` or `>=24.0.0` with npm.
- A local machine on which you trust same-user agent tools. No model or platform key is needed to open the UI.

### Start with npm

```sh
npx --yes @clawdsh/cli@next
```

The command installs or upgrades the managed `clawdsh` profile under `$DSH_HOME` (default `~/.dsh`), then starts the foreground Web Host. Open the printed URL, normally `http://127.0.0.1:3080/clawdsh/`. Press `Ctrl-C` to stop it; the launcher forwards terminal signals and waits for dsh to close.

The first run creates only installer-owned profile, preset, dependency, and management files. It does not require or create an OpenClaw runtime, platform login, model key, Memory fact, Automation rule, or external Channel listener. See the [complete CLI reference](packages/openclaw/preset-openclaw/distribution/cli/README.md) for global installation, custom host/port values, upgrades, migration, backups, and failure behavior.

## Credentials

ClawDSH separates model, embedding, and platform credentials so one UI or file never becomes an all-secrets store.

| Credential | Where to set it | When it is needed | Effect timing |
|---|---|---|---|
| DeepSeek `DEEPSEEK_API_KEY` | Settings → Models; `$DSH_HOME/.credentials.yaml`; launch environment; or `.env` | The first DeepSeek model or Web Search request | Managed credential file: next call; environment and `.env`: restart |
| Ark `ARK_API_KEY` | Settings → ClawDSH → Memory → Ark; `$DSH_HOME/.credentials.yaml`; launch environment; or `.env` | The first Ark embedding request | Managed credential file: next call; environment and `.env`: restart |
| Platform account credentials | OpenClaw account setup and `$DSH_HOME/clawdsh/channel/openclaw/state/openclaw.json` after `clawdsh channel install` | Only an explicitly enabled OpenClaw platform route | OpenClaw-owned; restart after account or policy changes |

The local managed credential document is ordinary YAML:

```yaml
DEEPSEEK_API_KEY: "<your-deepseek-key>"
ARK_API_KEY: "<your-ark-key>"
```

Credential precedence is inherited launch environment → `$DSH_HOME/.credentials.yaml` → the invoking directory's `.env` → `$DSH_HOME/.env`. The UI never returns secret values through Settings RPC, and ClawDSH never copies OpenClaw platform credentials into dsh credentials, logs, sessions, Activity, or its management marker.

`$DSH_HOME/.credentials.yaml` is stored with owner-only permissions. Mode `0600` protects against other operating-system users; it cannot stop a shell or filesystem tool running under the same UID from deliberately reading the file. Run ClawDSH only on a trusted host, keep secrets out of `settings.yaml`, profile patches, issue reports, and screenshots, and secure any backup that contains the credential document.

## Configuration and data

### Four configuration domains

| Domain | Authoritative location | User entry and precedence | Ownership rule |
|---|---|---|---|
| Non-secret product settings | `$DSH_HOME/settings.yaml` | Settings → ClawDSH; schema defaults → managed profile base → user settings | ClawDSH exposes exactly eight product namespaces and classifies every field as editable, managed, or hidden |
| Model and Ark secrets | `$DSH_HOME/.credentials.yaml`, launch environment, and `.env` | Settings → Models or Memory → Ark; environment wins over the managed file and both `.env` layers | Secret values never belong in `settings.yaml` or a profile patch |
| Deployment composition and advanced overrides | Installed bundle plus `$DSH_HOME/profiles/clawdsh/cordis.patch.yml` and the home-level `$DSH_HOME/cordis.patch.yml` | Bundle layers → profile patch → home patch; later layers win | The installer owns the bundle and dependency tree but preserves user patch bytes |
| OpenClaw accounts and policy | `$DSH_HOME/clawdsh/channel/openclaw/state/openclaw.json` | `clawdsh channel install`, then OpenClaw account and policy tools | OpenClaw owns platform state; ClawDSH validates deployment identity but does not duplicate the state |

The Settings page displays each field's owner and effect timing. `live` changes affect the mounted runtime, `new-session` changes require a new conversation, `next-call` changes are resolved for the next operation, and `restart` changes take effect after restarting ClawDSH. Soul is new-session scoped; Automation settings apply live; Memory and Skills provider changes require restart; managed credential-file changes are visible on the next call. The [generated configuration catalog](docs/config-catalog.md) is the exhaustive field reference; README examples intentionally cover only common entries.

### Data locations and backups

| Data | Default location | Managed install or migration behavior |
|---|---|---|
| Settings and credentials | `$DSH_HOME/settings.yaml`, `$DSH_HOME/.credentials.yaml` | Never read, moved, or rewritten by source migration; Settings writes only the selected user namespace |
| Sessions | `$DSH_HOME/sessions` | Preserved across install, upgrade, preset reset, and source migration |
| Memory and Activity | `$DSH_HOME/memory`, `$DSH_HOME/clawdsh/activity/v1` | Preserved; Activity remains privacy-limited and non-blocking |
| Managed profile and presets | `$DSH_HOME/profiles/clawdsh`, `$DSH_HOME/.agent-presets/{clawdsh,clawdsh-messaging-safe}` | Installer-owned; modified presets require an explicit backup-before-reset action |
| OpenClaw runtime and state | `$DSH_HOME/clawdsh/channel/openclaw` | Acquired only by `channel install`; existing configuration and state are preserved |
| Compatible managed skills | `~/.clawdbot/skills` | Outside `$DSH_HOME` by default; set Skills Hub `managedDir` to choose another directory |

For a complete operator backup, stop ClawDSH and snapshot the entire `$DSH_HOME` plus `~/.clawdbot/skills` or the configured external `managedDir`. Installer-created source-migration and preset backups cover only the named profile/preset assets; they are not substitutes for a user-data backup. Restore a full snapshot only while ClawDSH is stopped, preserve owner-only permissions, and run `npx --yes @clawdsh/cli@next doctor` before starting.

## Maintenance and troubleshooting

### Update, diagnose, and migrate

```sh
npx --yes @clawdsh/cli@next
npx --yes @clawdsh/cli@next doctor
npx --yes @clawdsh/cli@next migrate source
npx --yes @clawdsh/cli@next migrate source --apply
npx --yes @clawdsh/cli@next migrate source --apply --backup-modified
npx --yes @clawdsh/cli@next channel install
npx --yes @clawdsh/cli@next channel doctor
```

Running the `next` entry again installs the current release candidate and performs an idempotent managed upgrade. `doctor` checks only the installer-owned profile, bundle, and presets; `channel d

... (truncated)

tools