Implementation:Openclaw Openclaw LoadWorkspaceBootstrapFiles

LoadWorkspaceBootstrapFiles

LoadWorkspaceBootstrapFiles documents the loadWorkspaceBootstrapFiles function in src/agents/workspace.ts and the resolveAgentWorkspaceDir function in src/agents/agent-scope.ts. Together, these load workspace-specific markdown files that define an agent's personality, capabilities, and instructions.

Principle:Openclaw_Openclaw_Persona_Customization

Source Locations

File	Lines	Description
src/agents/workspace.ts	L237-291	loadWorkspaceBootstrapFiles()
src/agents/agent-scope.ts	L167-182	resolveAgentWorkspaceDir()
src/agents/workspace.ts	L58-74	WorkspaceBootstrapFile type
src/agents/workspace.ts	L21-29	Bootstrap filename constants
src/agents/workspace.ts	L295-303	filterBootstrapFilesForSession()

loadWorkspaceBootstrapFiles

Signature

export async function loadWorkspaceBootstrapFiles(
  dir: string,
): Promise<WorkspaceBootstrapFile[]>

Parameters

Parameter	Type	Description
dir	string	The workspace directory path. Supports ~ expansion via resolveUserPath().

Return Type

export type WorkspaceBootstrapFile = {
  name: WorkspaceBootstrapFileName;
  path: string;
  content?: string;
  missing: boolean;
};

Field	Type	Description
name	WorkspaceBootstrapFileName	The canonical filename (e.g., "AGENTS.md", "SOUL.md").
path	string	The resolved absolute file path.
content	string (optional)	File content when the file exists. Undefined when missing.
missing	boolean	true when the file does not exist in the workspace.

Bootstrap File Constants

export const DEFAULT_AGENTS_FILENAME = "AGENTS.md";
export const DEFAULT_SOUL_FILENAME = "SOUL.md";
export const DEFAULT_TOOLS_FILENAME = "TOOLS.md";
export const DEFAULT_IDENTITY_FILENAME = "IDENTITY.md";
export const DEFAULT_USER_FILENAME = "USER.md";
export const DEFAULT_HEARTBEAT_FILENAME = "HEARTBEAT.md";
export const DEFAULT_BOOTSTRAP_FILENAME = "BOOTSTRAP.md";
export const DEFAULT_MEMORY_FILENAME = "MEMORY.md";
export const DEFAULT_MEMORY_ALT_FILENAME = "memory.md";

Algorithm

1. Resolve the workspace directory path via resolveUserPath(dir).
2. Build the list of entries for the seven core files: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md.
3. Resolve memory entries via resolveMemoryBootstrapEntries(), which checks for both MEMORY.md and memory.md with deduplication (using fs.realpath to avoid loading the same inode twice).
4. Read each file:
   • If the file exists, read its content and include it with missing: false.
   • If the file does not exist, include it with missing: true and no content.
5. Return the array of all entries.

Error Handling

Missing files are not errors. The function gracefully handles missing files by setting missing: true, allowing callers to decide whether a missing file is acceptable. File read errors (other than ENOENT) propagate as exceptions.

resolveAgentWorkspaceDir

Signature

export function resolveAgentWorkspaceDir(
  cfg: OpenClawConfig,
  agentId: string,
): string

Parameters

Parameter	Type	Description
cfg	OpenClawConfig	The full gateway configuration.
agentId	string	The agent whose workspace directory to resolve.

Return Value

Returns the resolved absolute path to the agent's workspace directory.

Resolution Priority

1. Agent-specific config: agents.list[].workspace for the matching agent, resolved via resolveUserPath().
2. Default agent fallback: If the agent is the default agent and agents.defaults.workspace is set, use that.
3. Global default: For the default agent, use DEFAULT_AGENT_WORKSPACE_DIR (influenced by OPENCLAW_PROFILE env var).
4. Convention-based: For non-default agents with no explicit workspace, use ~/.openclaw/workspace-<agentId>.

export function resolveAgentWorkspaceDir(cfg: OpenClawConfig, agentId: string) {
  const id = normalizeAgentId(agentId);
  const configured = resolveAgentConfig(cfg, id)?.workspace?.trim();
  if (configured) {
    return resolveUserPath(configured);
  }
  const defaultAgentId = resolveDefaultAgentId(cfg);
  if (id === defaultAgentId) {
    const fallback = cfg.agents?.defaults?.workspace?.trim();
    if (fallback) {
      return resolveUserPath(fallback);
    }
    return DEFAULT_AGENT_WORKSPACE_DIR;
  }
  return path.join(os.homedir(), ".openclaw", `workspace-${id}`);
}

filterBootstrapFilesForSession

Signature

export function filterBootstrapFilesForSession(
  files: WorkspaceBootstrapFile[],
  sessionKey?: string,
): WorkspaceBootstrapFile[]

Behavior

For sub-agent sessions (detected via isSubagentSessionKey(sessionKey)), only AGENTS.md and TOOLS.md are returned. All other bootstrap files are filtered out to prevent personality bleed from parent to child agents.

For regular sessions (or when no session key is provided), all files are returned unfiltered.

Related Functions

Function	File	Purpose
ensureAgentWorkspace(params)	src/agents/workspace.ts	Creates workspace directory and seeds template files using write-if-missing semantics.
resolveDefaultAgentWorkspaceDir(env, homedir)	src/agents/workspace.ts	Computes the default workspace path, incorporating OPENCLAW_PROFILE.
resolveAgentDir(cfg, agentId)	src/agents/agent-scope.ts	Resolves the agent state directory (separate from workspace).
resolveAgentConfig(cfg, agentId)	src/agents/agent-scope.ts	Looks up the full agent config entry by id.