---
title: 从源码运行与调试
description: 给产品贡献代码时使用本机 Node.js 开发环境。
lastVerified: 2026-09-23
---

# 6.7 从源码运行与调试

日常开发推荐 **本机 Teloa / Harness + Docker PostgreSQL**。这样可以直接调试本机文件、程序、PATH 与工具权限，也与规划中的 npm 原生安装保持同一执行方式。当前需要本机操作的用户也可按本页从源码运行；不同安装方式见[安装指南](https://docs.teloa.ai/markdown/start/quickstart.md)。

全容器 Compose 可用于隔离集成测试与部署回归；本机程序和系统权限仍需在原生环境验证，详见[测试环境分工](https://docs.teloa.ai/markdown/develop/testing.md)。

## 环境与启动

需要已取得源码、Node `^22.19.0 || >=24.0.0`、pnpm `11.7.0` 和可连接的本机 Docker。

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

启动器会先构建，并输出当前认证地址。使用完整地址进入。不要把令牌提交到仓库或错误报告。

这组命令在本机运行应用，只把数据库放入 Docker。当前 `setup:database` 默认需要可用的本机 Docker；npm 安装器中“使用已有本机数据库”的选择流程仍在规划中。

## 本机工作目录与工具

默认工作目录为 `.runtime/teloa/workspace`。可通过 `TELOA_WORKSPACE_ROOT` 显式指定自己的工作目录，但不能使用 Teloa 程序目录、其上级目录或程序目录中运行目录以外的位置。切换工作目录不会自动搬迁原有文件。

Harness 从工作目录调用获授权的工具。程序是否可用取决于工具接入、启动环境的 PATH 和操作系统权限；原生运行不等于开放整台电脑。修改 PATH 后应重启服务并实测。浏览器、桌面和办公软件操作还需要对应工具，不能用“安装完成”作为已具备这些能力的证据。

## 修改后的验证

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

按修改范围补跑后端、Harness 或浏览器测试。插件配置与界面构建通常需要重新构建并重启宿主，不能依赖浏览器刷新自动加载新代码。

## 隔离运行

使用仓库提供的 `pnpm dev:dsh:acceptance` 验收启动器，按其提示创建独立 profile、端口、工作目录和数据库范围。不要只改一个端口就复用正式工作数据。

默认 3100 是日常宿主。结束验收时只操作自己启动的进程，不按模糊关键词批量终止。

## 排查日志

先看启动命令的错误，再看 `.runtime/teloa/harness.log` 和相应执行记录。分享前删除令牌、Cookie、密钥、数据库连接和私人内容。构建输出、模型错误和业务状态错误应分别记录。