datawhalechina/hello-agents · error · SystemExit

❌ 初始化 Agent 失败: {e}

Error message

❌ 初始化 Agent 失败: {e}

What it means

CLI chat command error: constructing HelloClawAgent(workspace_path) threw, the message is printed in red to the console, and the process exits via SystemExit(1). The most common underlying cause is an invalid or missing config.json llm block (bad API key / base_url / model_id) or an unreachable LLM endpoint during client construction.

Source

Thrown at Co-creation-projects/tino-chen-HelloClaw/src/cli/main.py:50

def chat(session_id: Optional[str], workspace: Optional[str]):
    """启动交互式对话（REPL 模式）"""
    from ..channels.cli_channel import CLIChannel
    from ..agent.helloclaw_agent import HelloClawAgent
    from ..workspace.manager import WorkspaceManager

    # 确定工作空间路径
    workspace_path = workspace or os.getenv("WORKSPACE_PATH", "~/.helloclaw/workspace")

    # 初始化工作空间
    ws = WorkspaceManager(workspace_path)
    ws.ensure_workspace_exists()

    # 初始化 Agent
    try:
        agent = HelloClawAgent(workspace_path=workspace_path)
    except Exception as e:
        console.print(f"[red]❌ 初始化 Agent 失败: {e}[/red]")
        raise SystemExit(1)

    # 启动 CLI Channel
    channel = CLIChannel(agent, session_id=session_id)
    asyncio.run(channel.run())


@cli.command()
@click.argument("question")
@click.option("--session", "-s", "session_id", default=None, help="指定会话 ID")
@click.option("--workspace", "-w", default=None, help="指定工作空间路径")
@click.option("--no-stream", is_flag=True, help="禁用流式输出")
def ask(question: str, session_id: Optional[str], workspace: Optional[str], no_stream: bool):
    """单次提问，输出结果后退出"""
    from ..agent.helloclaw_agent import HelloClawAgent
    from ..workspace.manager import WorkspaceManager

    # 确定工作空间路径
    workspace_path = workspace or os.getenv("WORKSPACE_PATH", "~/.helloclaw/workspace")

View on GitHub (pinned to 606a07d341)

Solutions

1. Read the exception text printed after the ❌ — it names the real failure
2. Open <workspace>/config.json and verify the llm block has valid model_id, api_key, base_url
3. Test base_url reachability with curl <base_url>/models using the same key
4. Check the workspace path is writable by the current user (ls -la ~/.helloclaw/workspace)

Example fix

# before
helloclaw chat   # exits: ❌ 初始化 Agent 失败: ...
# after
# fix config first
cat ~/.helloclaw/workspace/config.json  # verify llm.model_id/api_key/base_url
curl -H "Authorization: Bearer $KEY" "$BASE_URL/models"  # verify credentials
helloclaw chat

import json, os
def agent_config_ok(ws_path: str) -> bool:
    p = os.path.join(os.path.expanduser(ws_path), 'config.json')
    try:
        cfg = json.load(open(p))
    except Exception:
        return False
    llm = cfg.get('llm', {})
    return all(k in llm for k in ('model_id', 'api_key', 'base_url'))

When it happens

Trigger: Running `helloclaw chat` (or the equivalent CLI entry) with ~/.helloclaw/workspace/config.json missing llm fields, an expired API key, or a base_url that cannot be reached; WORKSPACE_PATH env pointing at a non-writable or uninitialized directory.

Common situations: First run before configuring the LLM; rotating an API key without updating config.json; behind a corporate proxy so the model client fails to initialize; workspace created by a different user so file writes raise.

Related errors

• API密钥和服务地址必须被提供或在.env文件中定义。
• llm 配置缺少必需字段: {', '.join(missing_fields)}
• 启动失败
• 工具 '{tool_name}' 不存在
• LLM思考超时

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