本地开发

本指南介绍如何在本地运行、调试和迭代 InnoClaw。

启动开发服务器

npm run dev

这将启动带有热模块替换（HMR）的 Next.js 开发服务器。应用程序可通过 http://localhost:3000 访问。

开发特性

  • 热重载 —— 组件和页面的更改会立即生效

  • API 路由重载 —— 服务端 API 更改在下次请求时生效

  • 错误覆盖层 —— 构建错误和运行时错误会在浏览器中显示

Dev Helper Scripts

Three shell scripts are provided for managing the development server in the background:

Start the Dev Server

bash dev-start.sh

This script checks for port conflicts, installs dependencies if needed, runs database migrations, and starts the dev server in the background. Logs are written to logs/dev.log and the server PID is tracked for later use.

Check Server Status

bash dev-status.sh

Reports whether the dev server is currently running.

Stop the Dev Server

bash dev-stop.sh

Stops the dev server using the stored PID.

常见开发任务

运行类型检查

npx tsc --noEmit

运行 Lint

npm run lint

使用 ESLint 及项目配置的规则。

生产环境构建

npm run build

创建优化的生产环境构建。这也会执行类型检查。

数据库操作

# Run migrations (apply schema changes)
npx drizzle-kit migrate

# Generate new migration files (after modifying schema.ts)
npx drizzle-kit generate

# Explore the database interactively
npx drizzle-kit studio

调试

服务端调试

  1. 使用 Node.js 调试器启动开发服务器：

    NODE_OPTIONS='--inspect' npm run dev

  2. 在 Chrome 中打开 chrome://inspect 并连接到 Node.js 进程

  3. 在 API 路由和服务端代码中设置断点

客户端调试

使用浏览器内置的开发者工具：

  • React DevTools —— 检查组件层级和状态

  • 网络选项卡 —— 监控 API 请求和响应

  • 控制台 —— 查看日志和错误

环境设置技巧

无 AI API 密钥

大部分功能无需配置 AI API 密钥即可开发：

  • 工作空间管理、文件浏览器和 UI 组件无需任何 API 密钥即可运行

  • AI 对话和笔记生成功能将显示"未配置"消息

多个根目录

用于测试多根目录的工作空间管理：

WORKSPACE_ROOTS=/tmp/workspace-a,/tmp/workspace-b

使用本地 AI 代理

如果您运行本地 LLM（例如通过 Ollama 或 LM Studio）并提供 OpenAI 兼容 API：

OPENAI_API_KEY=dummy-key
OPENAI_BASE_URL=http://localhost:11434/v1