---
title: 安装与运行 Teloa
description: 从 GitHub Release 或 Docker Hub 安装 Teloa 社区版 0.2.3 正式版，了解升级、运行位置和权限范围；npm 提供同版原生包。
lastVerified: 2026-10-19
---

# 1.2 安装与运行 Teloa

Teloa 的服务可以在本机直接运行，也可以放入容器。两种方式都通过浏览器使用现有 Web 界面，区别在于工具在哪里执行、能访问哪些文件和程序。

## 选择运行方式

当前版本：**0.2.3**。可选择 [npm](https://www.npmjs.com/package/@teloa/cli)、[GitHub Release](https://github.com/teloa-ai/teloa/releases/tag/v0.2.3) 或 [Docker Hub](https://hub.docker.com/r/teloa/teloa) 安装。

- **npm 原生安装**：无需源码或编译，应用和智能体引擎 DSH 在本机 Node.js 中运行，默认使用 Docker PostgreSQL。按下文安装。
- **Docker Hub + Compose**：应用、智能体引擎与数据库均在容器内，使用下文可下载的版本配置。正式镜像已验 Linux ARM64，amd64 尚未验证。
- **源码运行**：适合开发和修改，按[本地开发指引](https://docs.teloa.ai/v/0.2.3/markdown/develop/local-development.md)启动。源码根目录仍可执行 `docker compose up -d --build` 自行构建。

需要调用自己电脑上的程序时，选择原生运行。容器中的 shell 执行容器内的程序；挂载指定文件夹只提供文件访问，不等于控制本机应用。部署在远端服务器上也不会自动获得个人电脑的文件访问权。

## 从 GitHub Release 原生安装

npm 安装器提供现有开源 Web 的安装与启停命令，用户仍在浏览器中工作。Teloa 和智能体引擎原生运行，数据库默认由 Docker 管理，也可选择已有的本机 `teloa` 专用 PostgreSQL，不连接任意远程数据库。

需要 Node.js 24.x 或 22.19 及以上的 22.x，以及 npm 11.12.1 及以上的 11.x。Node.js 22 自带的 npm 10 需先升级。

所有方式都需要自行配置模型；使用远程模型时，准备相应服务的 API 密钥。原生安装保留工具授权、工作目录与审批边界，桌面或浏览器操作需要另外接入相应工具。平台支持以实际验收范围为准。

### 1. 安装并启动

将精确版本安装到独立命令目录，选择空闲端口。以下安装正式版 `0.2.3`；先运行 `up` 初始化，再核对运行状态：

```sh
npm install --prefix ./teloa-command --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.3/teloa-cli-0.2.3.tgz
./teloa-command/node_modules/.bin/teloa up --port 3101
./teloa-command/node_modules/.bin/teloa doctor
./teloa-command/node_modules/.bin/teloa status
```

可用[发行页](https://github.com/teloa-ai/teloa/releases/tag/v0.2.3)的 `SHA256SUMS` 核对下载。从 npm 安装同版可使用 `npm install --ignore-scripts @teloa/cli@0.2.3`。

下文 `teloa` 指该命令目录中的 `node_modules/.bin/teloa`。默认安装目录为 `~/.teloa`；新安装可通过 `--home`、`--port`、`--workspace` 指定目录和端口。浏览器未自动打开时运行 `teloa open`。进入后[配置模型](https://docs.teloa.ai/v/0.2.3/markdown/start/models.md)，再[新建项目](https://docs.teloa.ai/v/0.2.3/markdown/guides/projects.md)。

使用已有 PostgreSQL 时，仅接受 `localhost` 或 `127.0.0.1` 上名为 `teloa` 的独立数据库；首次安装必须为空库，不接管其他安装。通过 `--database-config` 提供包含 `connectionString` 的 JSON 文件，权限应为 `0600`；不要把连接凭据放入命令行或公开日志。

更新 npm 命令包不会自动替换运行中的应用。从已有 Alpha 或 Beta 安装升级时，保留原 `--home`，使用下方正式版命令包先停止并备份，再运行 `teloa upgrade --to 0.2.3`。升级会自动备份并核对候选就绪，不要覆盖程序目录或重新初始化原数据库。

将已有安装（例如 `0.2.0-alpha.7`）升级到正式版时，先把 `0.2.3` 命令包安装到新的命令目录，再用它停止原安装并升级。自定义安装继续传入原 `--home`：

```sh
npm install --prefix ./teloa-command-023 --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.3/teloa-cli-0.2.3.tgz
./teloa-command-022/node_modules/.bin/teloa stop
./teloa-command-023/node_modules/.bin/teloa upgrade --to 0.2.3
./teloa-command-022/node_modules/.bin/teloa status
```

`--to` 等于当前命令包版本时，升级使用该命令包作为候选；其他版本仍从 npm 注册表取得。升级保留原安装身份、端口、工作目录和数据，并在切换前自动备份。只运行新命令包的 `up` 不会替换原安装，会继续启动原版本并提示升级命令。

### 2. 环境检查

```sh
teloa doctor
teloa doctor --json
```

尚未初始化也能检查 Node、PATH 中的 npm 与真实终端沙箱，不会创建安装目录或启动数据库。任何检查未通过时退出码为 `1`，文本会给出建议，JSON 中对应项的 `ok` 为 `false` 并带 `remedy`。已有安装还会检查运行依赖、目录、数据库和服务。

Linux 受限终端需要可运行的 bubblewrap 或支持 Landlock 的内核；某些 Docker 或模拟环境不具备条件。请修复环境后重跑检查，不要关闭沙箱。诊断通过后仍需[配置并测试模型](https://docs.teloa.ai/v/0.2.3/markdown/start/models.md)；Web 就绪不等于终端任务或模型已可用。更多情况见[故障排查](https://docs.teloa.ai/v/0.2.3/markdown/deploy/troubleshooting.md)。

### 3. npm 安装的停止与继续

使用同一命令目录中的 CLI。停止后保留安装数据：

```sh
teloa status
teloa stop
teloa up
```

停止前先处理运行中的工作；使用自定义安装目录时，继续传入原来的 `--home`。更换版本前先看[备份与升级](https://docs.teloa.ai/v/0.2.3/markdown/deploy/backup.md)。

## 使用 Docker Compose

以下步骤会把 Teloa 和 PostgreSQL 放入容器，数据保存在持久卷中。本机无需安装 Node.js、pnpm 或 OrbStack。

### 开始前

- 安装并启动 [Docker Desktop](https://docs.docker.com/desktop/) 或装有 Docker Compose 的 [Docker Engine](https://docs.docker.com/engine/install/)。
- 使用 Linux ARM64 环境。下文镜像与配置固定为 `teloa/teloa:0.2.3`；amd64 尚未验证。
- 网络能够下载镜像和软件依赖；模型由你自行配置，远程服务需要相应 API 密钥。

新建一个目录，下载[本版本 Compose 配置](https://docs.teloa.ai/v/0.2.3/downloads/0.2.3/compose.yaml)。配置沿用密码初始化、独立数据库与持久卷，不需要编译源码。

```sh
docker info
docker compose version
```

前者应返回运行中的引擎信息，后者显示 Compose 版本。使用当前维护的 Docker，确保支持健康检查和初始化服务的依赖条件。

### 启动

在新的目录中执行：

```sh
mkdir teloa-free
cd teloa-free
curl --fail --location https://docs.teloa.ai/downloads/0.2.3/compose.yaml --output compose.yaml
docker compose pull
docker compose up -d --no-build
```

首次启动使用正式镜像，依次生成数据库口令、初始化数据库并启动 Teloa。口令保存在独立卷中，不需要填写演示密码。

### 查看状态

```sh
docker compose ps
```

等待 `db` 与 `app` 健康。`init` 是一次性初始化服务，成功退出属于正常行为。持续重启时先[检查错误](https://docs.teloa.ai/v/0.2.3/markdown/deploy/troubleshooting.md)，不要删除数据卷。

默认 Web 端口为本机 `3100`，数据库端口不开放到容器外。已有服务占用时，在本目录 `.env` 中填写 `TELOA_PORT=3101`，再启动；不要结束无关服务。

### 打开认证链接

```sh
docker compose logs --tail=50 app
```

在自己的终端找到本次启动输出的完整认证链接。更改过端口时，将链接的端口改为你设置的端口，并保留完整认证参数。

重启后使用新链接。认证链接不是模型密钥，也不要把含认证参数的日志贴到公开问题中。

### 开始工作

首次进入时可能会提示添加 API 密钥；可以当场配置，也可以选择“稍后配置”，再进入 **设置 > 模型**。按[模型指南](https://docs.teloa.ai/v/0.2.3/markdown/start/models.md)验证一次回应。页面可用和模型可用是两个不同结果。

[![尚未配置模型时，工作台的模型选择显示“暂无可用模型”](https://docs.teloa.ai/v/0.2.3/assets/screenshots/model-key-022.fda2951c54b9.png)](https://docs.teloa.ai/v/0.2.3/assets/screenshots/model-key-022.fda2951c54b9.png)

*0.2.2 界面，尚未填写密钥。模型选择显示“暂无可用模型”时，到 设置 > 模型 填入模型服务商的 API 密钥；它不是上一步的本机认证链接。*

接着[完成第一项任务](https://docs.teloa.ai/v/0.2.3/markdown/start/first-task.md)或[组建第一支团队](https://docs.teloa.ai/v/0.2.3/markdown/start/first-team.md)。初始环境可能为空，不要求先导入演示数据。

### 停止与继续

```sh
docker compose stop
docker compose start
```

数据保留在持久卷中。电脑休眠、关机或 Docker 退出后，本机任务和自动化无法继续执行。升级前先[备份](https://docs.teloa.ai/v/0.2.3/markdown/deploy/backup.md)；修改源码请看[本地开发](https://docs.teloa.ai/v/0.2.3/markdown/develop/local-development.md)。