6.12 从源码运行与调试

修改 Teloa 源码时，应用在本机运行，PostgreSQL 放在本机 Docker。只开发模板或 SKILL 时，使用已安装的 Teloa 即可，不必搭建本页环境。

准备环境

需要 Git、Node.js 22.19 及以上的 22.x 或 24.x、pnpm 11.7.0 和已启动的本机 Docker。本版实际验收使用 Node.js 24.22.1；本套示例统一按 Node 24 编写。

git clone https://github.com/teloa-ai/teloa.git
cd teloa
node --version
pnpm --version
docker info
pnpm install --frozen-lockfile
pnpm setup:dsh

这些命令都在源码根目录执行。依赖和运行脚本以当前检出的 package.json、锁文件和固定 DSH 基线为准。

启动自己的开发实例

在没有已有 Teloa 开发数据的新检出中执行：

pnpm setup:database
pnpm dev:dsh

数据库准备器会检查本机 teloa-postgres 容器的归属，归属冲突时拒绝接管。不要为通过检查而删除已有容器、卷或数据库配置。

启动器先构建，再输出带认证令牌的本机地址。打开完整地址，在设置中配置测试模型，发送一条简单消息并查看真实回复。默认端口是 3100；若已被使用，保留原服务并采用下面的验收启动器。不要只换端口后继续复用原数据。

已有开发数据库时运行隔离验收

pnpm dev:dsh:acceptance

它读取本机已初始化的开发数据库配置，在同一数据库中建立独立 schema，并自动分配端口、profile、运行目录和工作目录。它不是交互式创建向导，也不创建新的 PostgreSQL 数据库。新数据库需先完成上一节的初始化；没有配置时会报错。

默认不复制本机模型密钥。在新实例的可信设置控件配置测试模型。结束时用该启动进程的正常停止方式，核对其清理回执；不使用模糊进程名批量终止其他实例。

修改并定位问题

先选架构表中对应的包。最小验证顺序：

pnpm check:dsh
pnpm test:contract

再运行受影响包的测试，见测试与贡献。界面或插件代码变化后，重新构建并重启自己启动的宿主；刷新浏览器不会加载新的服务端代码。

默认任务文件在 .runtime/teloa/workspace，不是源码目录。需要其他工作目录时，通过启动环境的 TELOA_WORKSPACE_ROOT 指定已授权目录；更改设置不搬迁原文件。

排错

现象	先检查
找不到 pnpm 或版本不符	PATH 与 packageManager，不要静默升级全局依赖
数据库准备失败	docker info、容器归属、已有数据库配置
端口冲突	原服务是否仍在使用；使用隔离实例
只有页面、没有模型回复	测试实例中的模型提供商、凭据与实际选模
改代码后表现没变	是否完成构建、是否重启了正确宿主

先看启动错误，再看当前实例的 Harness 日志与执行记录。分享日志前去掉令牌、Cookie、密钥、数据库连接和私人正文。