@wujie-shell/config

@wujie-shell/config is the product configuration loader for wujie-shell. It reads a UI product project's environment files and shell.config.mjs, then normalizes paths, ports, runtime directories, model config, and OpenClaw asset locations for shell-core.

Responsibility

• Load product env files before importing product config.
• Locate shell.config.mjs or shell.config.js in a product root.
• Normalize relative paths into absolute paths.
• Resolve the product data directory under the current user's home directory.
• Provide canonical OpenClaw config/state paths.
• Create shell state directories before runtime or gateway startup.

This package must not contain product-specific Agent, Skill, Plugin, or UI logic. It only validates and normalizes the product contract.

Env Loading

loadShellEnv(projectRoot, options) loads env files from the product root.

Default mode is selected from:

1. options.mode
2. WUJIE_SHELL_ENV
3. NODE_ENV

Loaded files:

• Always: .env
• Local/dev mode: .env.local
• Prod mode: .env.prod, .env.prod.local

Existing process.env values win over file values. Env file values are only assigned when the key is not already present.

Shell Config Loading

loadShellConfig(projectRoot) loads env first, imports the product config, and returns a normalized config object.

Required product fields:

• appId
• productName
• protocol
• dataDirName

Important rules:

• dataDirName cannot be .wujieai.
• renderer defaults to ./src.
• ports.renderer defaults to 5273.
• ports.gatewayStart defaults to 12900.
• logger.logsDirName defaults to <dataDirName>/logs and resolves under the current user's home directory, like dataDirName.
• openclaw.nodeVersion defaults to 22.22.1.
• openclaw.openclawVersion defaults to 2026.6.1.
• openclaw.agentsDir defaults to ./agents.
• openclaw.skillsDir defaults to ./skills.

Exported API

import {
  ensureShellStateDirs,
  getConfigPaths,
  loadShellConfig,
  loadShellEnv,
  normalizeShellConfig,
  readJsonFile,
  writeJsonFile,
} from '@wujie-shell/config'

loadShellEnv(projectRoot, options?)

Loads product env files and returns:

{
  mode: 'local' | 'prod' | string,
  files: string[]
}

loadShellConfig(projectRoot)

Returns normalized shell config:

{
  projectRoot,
  configPath,
  appId,
  productName,
  protocol,
  renderer,
  dataDirName,
  dataDir,
  logger: {
    logsDirName,
    logsDir
  },
  ports: {
    renderer,
    gatewayStart
  },
  openclaw: {
    nodeVersion,
    openclawVersion,
    pluginSpecs,
    localPluginPaths,
    resolvedLocalPluginPaths,
    agentsDir,
    skillsDir,
    workflowsDir
  },
  models,
  capabilities
}

normalizeShellConfig(raw, projectRoot, configPath?)

Normalizes an already-loaded config object. Use this in tests or tooling that constructs config in memory.

getConfigPaths(shellConfig)

Returns canonical state paths:

{
  stateDir,
  configPath,
  lastGoodConfigPath,
  runtimeStateDir,
  logsDir,
  deviceIdentityPath
}

For playground these resolve under ~/.wujie-shell-playground by default. logger.logsDirName is a local machine directory name resolved as ~/<logger.logsDirName>, matching the dataDirName convention. It must not be an absolute path or escape the user home directory.

ensureShellStateDirs(shellConfig)

Creates the product data directory and child directories required by OpenClaw config, logs, runtime state, and device identity.

readJsonFile(path, fallback?) / writeJsonFile(path, value)

Small JSON helpers used by shell-core controllers.

Typical Usage

import { loadShellConfig } from '@wujie-shell/config'

const shellConfig = await loadShellConfig('apps/playground')
console.log(shellConfig.dataDir)

Product Boundary

shell.config.mjs belongs to the UI product. The shell reads it but does not own product assets. Agent, Skill, Plugin, and Workflow declarations should stay in the UI project and be referenced by config fields such as openclaw.localPluginPaths, openclaw.agentsDir, and openclaw.skillsDir.