What causes "AGENTS.md 配置文件不存在，请检查工作空间初始化" in datawhalechina/hello-agents?

Run the workspace initialization/onboarding step provided by HelloClaw (the one that writes AGENTS.md) before starting the agent.

datawhalechina/hello-agents · error · RuntimeError

AGENTS.md 配置文件不存在，请检查工作空间初始化

Error message

AGENTS.md 配置文件不存在，请检查工作空间初始化

What it means

HelloClawAgent._build_system_prompt calls workspace.load_config("AGENTS") and raises RuntimeError when it returns falsy. AGENTS.md is the mandatory core of the agent's system prompt (other configs like BOOTSTRAP are optional add-ons), so its absence means the workspace was never initialized through the intended onboarding/setup flow. This fails at prompt-build time, i.e. on the first conversation turn, not at agent construction.

Source

Thrown at Co-creation-projects/tino-chen-HelloClaw/src/agent/helloclaw_agent.py:201

            if hasattr(self, '_agent'):
                self._agent.llm = self._llm

            return True
        return False

    def _build_system_prompt(self) -> str:
        """构建系统提示词

        从 AGENTS.md 读取主要内容，附加其他配置文件作为上下文。
        如果入职未完成，注入 BOOTSTRAP.md 引导内容。

        Raises:
            RuntimeError: 如果 AGENTS.md 不存在
        """
        # 从 AGENTS.md 读取（必须存在）
        agents_content = self.workspace.load_config("AGENTS")
        if not agents_content:
            raise RuntimeError("AGENTS.md 配置文件不存在，请检查工作空间初始化")

        base_prompt = agents_content

        # 加载其他配置文件作为上下文
        context_parts = []

        # 检查入职是否完成
        if not self.workspace.is_onboarding_completed():
            bootstrap = self.workspace.load_config("BOOTSTRAP")
            if bootstrap:
                context_parts.append(f"\n## 初始化引导\n\n{bootstrap}")

        # 身份信息
        identity = self.workspace.load_config("IDENTITY")
        if identity:
            context_parts.append(f"\n## 你的身份信息\n{identity}")

        # 用户信息

View on GitHub (pinned to 606a07d341)

Solutions

Run the workspace initialization/onboarding step provided by HelloClaw (the one that writes AGENTS.md) before starting the agent.
If init already ran, check the workspace path the agent was constructed with and list its files to confirm AGENTS.md exists with exact casing.
Create a minimal AGENTS.md manually (project overview + coding conventions) to unblock, then complete onboarding.
Re-run init after fixing the underlying write failure (permissions, disk space).
Add a startup assertion: fail at construction, not first turn, when AGENTS.md is missing.

Example fix

# before
agent = HelloClawAgent(name="claw", workspace=WorkspaceManager("./ws"))
agent.run("hi")  # RuntimeError at prompt build
# after
ws = WorkspaceManager("./ws")
if not ws.load_config("AGENTS"):
    ws.init_workspace()  # or: raise SystemExit("workspace not initialized — run init first")
agent = HelloClawAgent(name="claw", workspace=ws)
agent.run("hi")

Defensive patterns

Strategy: validation

Validate before calling

ws = WorkspaceManager(workspace_path)
if not ws.load_config("AGENTS"):
    raise SystemExit(
        f"workspace at {workspace_path} is not initialized — "
        "run the HelloClaw init/onboarding step (creates AGENTS.md) first"
    )

Type guard

def workspace_is_ready(ws) -> bool:
    return bool(ws.load_config("AGENTS"))

Try / catch

try:
    agent.run(user_msg)
except RuntimeError as e:
    if "AGENTS.md" in str(e):
        raise SystemExit("workspace not initialized — run init before chatting") from e
    raise

Prevention

Run workspace init as part of first-run bootstrap, verified in CI
Check AGENTS.md existence at agent construction, not first turn
On case-sensitive filesystems use exact casing AGENTS.md

When it happens

Trigger: Starting HelloClawAgent against a fresh/empty workspace directory where init (which writes AGENTS.md) was skipped; workspace path misconfigured so load_config reads the wrong directory; AGENTS.md deleted or renamed (agents.MD, agents.md casing on a case-sensitive FS); a previous init run failed halfway leaving other configs present but AGENTS.md missing.

Common situations: New clone used immediately without the workspace-init command; running on Linux after creating the file as AGENTS.md on macOS/Windows then copying with wrong case; init crash (permissions, disk) after creating the directory but before writing AGENTS.md; tests pointing at a temp workspace with no fixtures.

Related errors

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/0562af40d9184a91. Report an issue: GitHub.