---
title: 从源码运行与调试
description: 克隆源码、准备依赖，在自己的开发环境启动工作台。
lastVerified: 2026-10-23
---

# 6.12 从源码运行与调试

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

## 准备环境

需要 Git、Node.js **22.19 及以上的 22.x 或 24.x**、pnpm 11.7.0 和已启动的本机 Docker。0.2.10 的已验收安全基线是 Node.js 24.22.1（或 22.23.4 及以上的 22.x）；本套示例统一按 Node 24 编写。

```sh
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 开发数据的新检出中执行：

```sh
pnpm setup:database
pnpm dev:dsh
```

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

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

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

```sh
pnpm dev:dsh:acceptance
```

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

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

## 修改并定位问题

先选[架构表](https://docs.teloa.ai/v/0.2.10/markdown/develop/architecture.md)中对应的包。最小验证顺序：

```sh
pnpm check:dsh
pnpm test:contract
```

再运行受影响包的测试，见[测试与贡献](https://docs.teloa.ai/v/0.2.10/markdown/develop/testing.md)。界面或插件代码变化后，重新构建并重启自己启动的宿主；刷新浏览器不会加载新的服务端代码。

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

## 排错

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

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