Neura Market Logo

OpenClaw Agent Runtime Workflow: Build, Test, and Validate

This page covers the developer workflow for the OpenClaw agent runtime, including type checking, linting, running tests, manual testing, and clean slate reset. It is intended for developers working on the agent runtime code.

Read this when

  • Working on OpenClaw agent runtime code or tests
  • Running agent-runtime lint, typecheck, and live test flows

Developer workflow for the agent runtime (src/agents/) inside the OpenClaw repository.

Type checking and linting

  • Local gate by default: pnpm check (typecheck, lint, policy guards)
  • Build gate: pnpm build when the change modifies build output, packaging, or lazy-loading/module boundaries
  • Full pre-push gate: pnpm build && pnpm check && pnpm check:test-types && pnpm test

Running Agent Runtime Tests

Execute the agent runtime unit test suites:

pnpm test \
  "src/agents/agent-*.test.ts" \
  "src/agents/embedded-agent-*.test.ts" \
  "src/agents/agent-hooks/**/*.test.ts"

The initial glob includes the agent-tools*, agent-settings, and agent-tool-definition-adapter* suites too.

Live tests are not part of the unit configuration; run them through the live wrapper (which sets OPENCLAW_LIVE_TEST=1 and requires provider credentials):

pnpm test:live src/agents/embedded-agent-runner-extraparams.live.test.ts

Manual testing

  • Start the Gateway in dev mode (bypasses channel connections with OPENCLAW_SKIP_CHANNELS=1): pnpm gateway:dev
  • Send one agent turn through the Gateway: pnpm openclaw agent --message "Hello" --thinking low
  • Launch the TUI for interactive debugging: pnpm tui

To examine tool call behavior, request a read or exec action so you can observe tool streaming and payload processing.

Clean slate reset

State is stored in the OpenClaw state directory: ~/.openclaw by default, or $OPENCLAW_STATE_DIR when that variable is defined. Paths relative to that directory:

PathHolds
openclaw.jsonConfig
state/openclaw.sqliteShared runtime state database
agents/<agentId>/agent/openclaw-agent.sqlitePer-agent model auth profiles (API keys + OAuth) and runtime state
credentials/Provider/channel credentials outside the auth profile store
agents/<agentId>/sessions/Transcript history and legacy session migration sources
sessions/Legacy single-agent session store (old installs only)
workspace/Default agent workspace (extra agents use workspace-<agentId>)

For a full reset, delete those paths. More targeted resets:

  • Sessions only: keep agents/<agentId>/agent/openclaw-agent.sqlite; session rows are stored there alongside other per-agent data. Use /new or /reset to begin a new session for a single chat, and openclaw sessions cleanup for session management.
  • Preserve auth: leave agents/<agentId>/agent/openclaw-agent.sqlite and credentials/ untouched.

Legacy auth-profiles.json files are no longer read during runtime; openclaw doctor --fix loads them into the SQLite store.

References