Agent runtime workflow

A recommended workflow for developing and testing changes to the OpenClaw agent runtime.

Type checking and linting

Run the default local gate before committing changes:

pnpm check

When a change can affect build output, packaging, or lazy-loading and module boundaries, also run the build:

pnpm build

For a full landing gate on agent-runtime changes, combine both:

pnpm check && pnpm test

Running agent runtime tests

Execute the core agent runtime test suites directly with Vitest:

pnpm test \
  "src/agents/agent-*.test.ts" \
  "src/agents/embedded-agent-*.test.ts" \
  "src/agents/agent-tools*.test.ts" \
  "src/agents/agent-settings.test.ts" \
  "src/agents/agent-tool-definition-adapter*.test.ts" \
  "src/agents/agent-hooks/**/*.test.ts"

To exercise live provider paths, prefix with the live-test flag:

OPENCLAW_LIVE_TEST=1 pnpm test src/agents/embedded-agent-runner-extraparams.live.test.ts

These commands cover the primary unit suites for agent execution, embedded runner behavior, tool definitions, settings, adapter logic, and runtime hooks.

Manual testing

The recommended manual flow starts the gateway in development mode, then exercises the agent and interactive surfaces:

pnpm gateway:dev

Send a direct agent message (delivered through connected channels):

pnpm openclaw agent --message "Hello" --thinking low

Launch the TUI for interactive sessions:

pnpm tui

To observe tool streaming and payload handling, include prompts that trigger read or exec actions.

Clean slate reset

Runtime state lives under the OpenClaw state directory (default ~/.openclaw). Set OPENCLAW_STATE_DIR to use a different location.

To reset the environment, clear these locations:

  • openclaw.json — configuration
  • agents/<agentId>/agent/auth-profiles.json — model auth profiles (API keys and OAuth)
  • credentials/ — provider and channel state outside the auth profile store
  • agents/<agentId>/sessions/ — agent session history
  • agents/<agentId>/sessions/sessions.json — session index
  • sessions/ — legacy session paths
  • workspace/ — to start from a blank workspace

To reset only sessions for one agent, delete agents/<agentId>/sessions/. To keep existing authentication, leave agents/<agentId>/agent/auth-profiles.json and any credentials/ entries in place.

Updated June 17, 2026