LangClaw

A modular agent framework for building tool-using assistants with Anthropic models.

Quick Start

npm install
npm run build

Set environment variables in .env:

ANTHROPIC_API_KEY=sk-ant-...
MODEL_ID=claude-sonnet-4-6
# optional
ANTHROPIC_BASE_URL=

Use As A Library

import { AgentLoop, createBuiltinTools } from 'langclaw'

const apiKey = process.env.ANTHROPIC_API_KEY!
const tools = createBuiltinTools(process.cwd())

const agent = new AgentLoop(apiKey, tools, {
  model: process.env.MODEL_ID || 'claude-sonnet-4-6',
  maxTokens: 8192,
  temperature: 0.7,
})

agent.addUserMessage('List files in this directory')
const result = await agent.run({ maxSteps: 10 })
console.log(result.finalResponse?.content)

Run Local H5 Demo

After installing this package, run:

langclaw

langclaw resolves a runtime directory automatically, then runs h5 (prefers npm run h5 when available), and prints the local link to open.

Resolution priority:

• --dir <path> / -C <path>
• LANGCLAW_RUNNERS_DIR (legacy: LANGCLAW_TEST_RUNNERS_DIR)
• nearest parent with package.json + scripts.h5
• runners / test-runners
• current directory fallback

If no scripts.h5 is found in the resolved directory, langclaw falls back to executing h5 directly (so h5 must be available in your PATH).

Available commands:

langclaw run      # 前台运行（默认）
langclaw start    # 后台启动
langclaw stop     # 停止后台进程
langclaw restart  # 重启后台进程
langclaw status   # 查看后台状态

When running in background, logs are written to:

runners/.langclaw-h5.log

Optional:

LANGCLAW_RUNNERS_DIR=/absolute/or/relative/path langclaw start
langclaw start --dir /absolute/or/relative/path

Manual fallback (build + start):

npm run build
npm start

Open:

http://127.0.0.1:3030

Endpoints:

• GET /health
• POST /api/chat with JSON body { "message": "..." }
• POST /api/reset

Optional env vars:

• DEMO_HOST (default 127.0.0.1)
• DEMO_PORT (default 3030)

Optional channel env vars:

• Telegram

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_ALLOWED_CHATS=12345,67890

• Feishu

FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx

Dev Runner (Debug REPL)

dev-runner.cjs is kept as a debugging tool, not the package entrypoint.

npm run start:dev-runner

Additional REPL commands:

• /channels - list registered channels
• /accounts - show configured bot accounts
• /bindings - list all routing bindings
• /route <channel> <peer> [account] [guild] - resolve route for a simulated inbound message
• /switch <agent|off> - force a specific agent (sage) or restore normal routing
• /gateway - start WebSocket gateway (ws://localhost:8765 by default)
• /lanes - show all named lanes (active/queued/max/gen)
• /enqueue <lane> <message> - manually enqueue work to a named lane
• /concurrency <lane> <N> - update lane max concurrency
• /generation - show lane generation counters
• /profiles - show auth profile status and last success time
• /cooldowns - show profiles currently in cooldown
• /simulate-failure <reason> - arm next API call failure (rate_limit, auth, timeout, billing, overflow, unknown)
• /fallback - show fallback model chain
• /stats - show resilience statistics (attempts/successes/failures/rotations)
• /heartbeat - show heartbeat status
• /trigger - trigger heartbeat once
• /cron - list cron jobs (reads workspace/CRON.json)
• /simulate-delivery-failure - toggle delivery failure rate between 0% and 50%
• /queue - list pending delivery queue entries
• /failed - list permanently failed delivery entries
• /delivery-stats - show delivery statistics

Publish Checklist

• npm run build succeeds and dist/ includes index + demo-server.
• npm test passes.
• README.md usage examples are up to date.
• package.json version is bumped.
• exports, types, and license are correct.