# QianjiangClaw Architecture

Updated: 2026-03-23

## 1. Stable Desktop Boundary

The stable boundary remains:

- Renderer
  - UI only
  - does not own raw runtime credentials
  - does not directly start runtime processes
- preload
  - exposes controlled desktop APIs to Renderer
- Electron Main
  - owns secret access
  - owns runtime cloud fetch
  - owns managed runtime config generation
  - owns bundled runtime lifecycle
- GatewayClient / RuntimeManager / cloud clients

## 2. Current Runtime-Cloud Design

Stage D step 1 uses a runtime-first cloud integration model.

The current key rule is:

- the user must first bind an OpenClaw employee `api_key`
- Electron Main uses that key to call `POST /openclaw-employee-config`
- the returned payload becomes the source of truth for runtime business configuration

This `api_key` is not the LLM vendor key. It is the OpenClaw employee identity credential.

## 3. Required Runtime-Side Clients

Main should include or add these runtime-side pieces:

- `OpenClawConfigClient`
  - calls `POST /openclaw-employee-config`
  - fetches runtime payload for startup
- later:
  - heartbeat client for `POST /openclaw-heartbeat`
  - event client for `POST /openclaw-employee-events`

## 4. Startup Flow for Stage D Step 1

Installer startup should follow this order:

1. Desktop app loads local settings.
2. Desktop app reads stored employee `api_key` from secret storage.
3. If missing, runtime startup is blocked and UI asks the user to bind the key.
4. If present, Main calls `POST /openclaw-employee-config` with:
   - `api_key`
   - `action = "init"`
5. Main validates returned runtime payload.
6. Main merges cloud payload with local machine-specific fields.
7. Main writes local managed runtime config.
8. `RuntimeManager.start()` launches bundled runtime using that managed config.
9. Gateway becomes available for the desktop product.

## 5. Runtime Config Responsibility Split

Cloud payload should provide runtime business configuration such as:

- `persona_prompt`
- `welcome_message`
- `work_hours`
- `auto_reply_rules`
- `resource_quota`
- `llm.model_id`
- `llm.temperature`
- `llm.max_tokens`
- `llm.provider.name`
- `llm.provider.base_url`
- `llm.provider.api_key`
- `skills`
- `channels`
- `config_version`
- runtime reporting endpoints

Desktop Main should still provide local host-specific fields such as:

- workspace path
- runtime state dir
- runtime logs dir
- managed config output path
- bundled Gateway bind and port
- generated gateway auth token for local control path

## 6. Security Rules

- Employee `api_key` lives in `SecretManager/keytar`.
- Renderer never receives raw `api_key`.
- Managed runtime config may contain effective runtime credentials, but diagnostics must not export raw sensitive values.
- If cloud config fetch fails, bundled runtime must remain unavailable instead of fake-ready.

## 7. Current State

Already in place:

- installer packaging
- bundled runtime payload delivery
- runtime detect/start/stop/restart/health/tailLogs
- managed config generation path exists locally
- diagnostics and UI pages already exist

Still missing for Stage D step 1:

- user-bound employee `api_key` flow
- `OpenClawConfigClient` wired to `POST /openclaw-employee-config`
- managed config generation from cloud payload
- real installer usability based on cloud-driven startup
