OpenComputer 是 Show HN 上出现的开源编码智能体项目,思路与 Devin 一类产品接近:你给它一个任务描述和一个代码仓库,它自己读代码、定位问题、改文件、跑测试,最后把改动交回来或提交 PR。区别在于它跑在你自己的机器或服务器上,模型用你自己的 API Key,代码不出内网。这篇教程按「装起来 → 接仓库 → 派活 → 验收」四段走一遍,跑通最小闭环。
适用场景
适合想在自己的代码库上试编码智能体、但不愿意把源码交给第三方 SaaS 的团队和个人。典型用法是修失败的单测、补文档、做小范围重构、批量改配置这类边界清楚的任务。如果你只是偶尔问几句代码问题,用聊天式工具更省事;想让它真的动仓库里的文件,才需要部署这套东西。
环境与前置条件
操作系统:Linux(Ubuntu 22.04 及以上的 LTS 版本比较省心)或 macOS。Windows 建议走 WSL2,原生环境容易在文件权限和路径映射上出问题。
运行时:Docker Engine + Docker Compose v2 是主要依赖,项目通常以容器方式分发。另外准备 Git 客户端,部分脚本可能用到 Python 3.10+ 或 Node 18+,具体以官方仓库 README 的当前版本要求为准。
硬件:
- 内存 8 GB 起步,16 GB 更稳(容器、仓库快照、测试进程会同时占内存)
- 磁盘预留 20 GB 以上,镜像和仓库副本比较占地方
- 显卡不是必须的。走云端模型 API 的路径,CPU 机器就够;只有想本地跑开源模型时才需要 GPU,显存需求按所选模型规模来,别在 8 GB 显存上硬塞大模型
账号与密钥:
- 一个模型服务的 API Key。项目一般对接 OpenAI 兼容接口,所以自建推理服务、云厂商的兼容端点、官方 API 都能用
- 一个 GitHub Personal Access AI 词典:Token">Token(后面接仓库用),细粒度 token 至少要给 Contents、Pull requests、Issues 的读写权限
网络:能拉取容器镜像、能访问模型服务端点。国内机器拉镜像慢的话,提前配好镜像加速,不然 docker compose up 会卡到怀疑人生。
分步骤部署
第 1 步:核对 Docker 环境
先确认基础环境在位,避免后面排错时来回猜。
```bash
docker version
docker compose version
```
成功的样子是两条命令都能打印出版本信息,且 Compose 显示为 v2.x。如果提示 permission denied while trying to connect to the Docker daemon socket,说明当前用户不在 docker 组,执行:
```bash
sudo usermod -aG docker $USER
newgrp docker
```
第 2 步:拉取代码并读一遍 README
```bash
git clone <官方仓库地址> opencomputer
cd opencomputer
ls
```
仓库地址以项目官方页面为准。进去后先看 README 和 docker-compose.yml(或 compose.yaml),重点确认三件事:默认暴露的端口是哪个、环境变量文件叫什么名字、有没有初始化脚本。不同版本结构会变,以仓库里实际文件为准,别照抄网上的旧教程。
第 3 步:配置模型
```bash
cp .env.example .env
```
用编辑器打开 .env,通常需要填这几类内容(变量名以 .env.example 里的实际写法为准):
```bash
模型服务:OpenAI 兼容接口
LLM_API_BASE=https://<你的模型服务地址>/v1
LLM_API_KEY=<你的密钥>
LLM_MODEL=<模型名称>
服务端口
APP_PORT=8080
仓库访问凭证
GITHUB_TOKEN=<你的 PAT>
```
两个容易踩的坑:LLM_API_BASE 一般要带 /v1 后缀,少了会返回 404;LLM_MODEL 必须和模型服务端实际暴露的模型名一字不差,多一个空格都会报模型不存在。改完 .env 记得别提交到 Git,先确认 .gitignore 里有它。
第 4 步:启动服务
```bash
docker compose up -d
docker compose ps
```
ps 里各服务状态显示为 running 或 healthy 就算起来了。第一次启动要拉镜像,可能几分钟。盯着日志看有没有异常:
```bash
docker compose logs -f --tail=100
```
日志里出现监听端口、数据库连接成功、worker 就绪之类的字样即可。按 Ctrl+C 退出日志跟踪,不影响容器运行。
第 5 步:打开控制台
浏览器访问 http://<服务器IP>:8080(端口以 .env 里 APP_PORT 为准)。能打开界面、能看到任务列表或新建任务的入口,说明 Web 层正常。如果服务器有防火墙或安全组,记得放行对应端口;只在本地用时可以只绑 127.0.0.1,通过 SSH 隧道访问更安全。
第 6 步:接入仓库
编码智能体要改代码,得先能读写仓库。两种常见接法:
方式一:Token 直连。 把第 3 步的 GITHUB_TOKEN 填好,在控制台的仓库配置里粘贴仓库地址,由系统自己 clone。PAT 权限不够时会 clone 失败,先确认 token 对目标仓库有 Contents 读写权限。
方式二:手动放到工作目录。 更适合先在本地试:
```bash
mkdir -p workspace
git clone https://<用户名>:<token>@github.com/<用户名>/<仓库名>.git workspace/<仓库名>
cd workspace/<仓库名>
git checkout -b agent-test
```
注意把 token 放在 URL 里会留在 shell 历史和 .git/config 中,测试完记得清理,正式环境建议换成 SSH key 或凭据助手。
第 7 步:下发第一个任务
别一上来就让它重构整个项目。挑一个失败的单测,把任务描述写清楚:目标、位置、验收标准、禁止事项。示例:
```
仓库:workspace/demo-api
任务:tests/test_user.py::test_user_create 目前失败,报错 KeyError: 'email'。
请定位根因并修复业务代码,不要修改测试文件里的断言。
完成后运行 pytest tests/test_user.py,确认全部通过,并输出改动说明。
```
提交后在界面上观察执行过程:读文件、改代码、执行命令的每一步一般都会打印出来。这时可以顺手留意它在读哪些文件——读偏了通常说明任务描述里的路径或关键词不够明确。
验证部署是否成功
三层验证,逐层确认:
服务层:健康检查接口返回正常。
```bash
curl -sS http://127.0.0.1:8080/healthz
```
路径以官方文档为准,返回 ok 或类似 JSON 即通过。同时 docker compose ps 里不应该有反复重启的容器。
模型层:直接在 .env 里那套配置上打一次请求,确认密钥和地址没问题。
```bash
curl -sS "$LLM_API_BASE/chat/completions" \
-H "Authorization: Bearer $LLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"'"$LLM_MODEL"'","messages":[{"role":"user","content":"ping"}]}'
```
能返回 choices 字段就说明模型链路通了。这一步报错,问题一定在密钥、地址或模型名上,跟智能体本身无关。
任务层:跑第 7 步那个修单测的任务,验收看三样东西:
```bash
cd workspace/demo-api
git status # 应该只看到预期的文件被改动
git diff # 逐行检查改动是否合理,有没有夹带无关修改
pytest -q tests/test_user.py # 测试是否真的通过了
```
git diff 这一步别省。智能体有时候会为了让测试变绿去改测试本身,或者加一堆 try/except 把异常吞掉——测试通过了但问题没解决。改动范围越小、越贴近根因,说明这一轮跑得越成功。
常见报错与解决
1. Bind for 0.0.0.0:8080 failed: port is already allocated
原因:端口被别的进程或旧容器占用。
```bash
ss -ltnp | grep 8080
docker ps -a | grep 8080
```
解决:杀掉占用进程,或改 .env 里的 APP_PORT 换个端口,然后 docker compose up -d 重建。
2. 模型请求返回 401 Unauthorized 或 404 Not Found
原因:密钥错误、LLM_API_BASE 少了 /v1、或者模型名对不上。
```bash
grep -E 'LLM_API_BASE|LLM_MODEL' .env
docker compose up -d --force-recreate
```
解决:用上文的 curl 命令单独测一遍模型端点,确认通了再重启容器。改完 .env 一定要 --force-recreate,否则容器还在用旧环境变量。
3. 容器内 clone 仓库报 Authentication failed 或 Repository not found
原因:PAT 权限不足、token 过期,或私有仓库没授权给这个 token。
```bash
docker compose exec <服务名> sh -c 'git ls-remote https://<用户名>:<token>@github.com/<用户名>/<仓库名>.git'
```
解决:重新签发 token,勾选目标仓库的 Contents 读写权限,更新 .env 后重建容器。
4. standard_init_linux.go: exec user process caused: exec format error
原因:镜像架构和机器架构不匹配,常见于在 ARM 机器(如 Apple Silicon)上跑 amd64 镜像。
解决:确认官方是否提供多架构镜像;没有的话在 compose 文件里加 platform: linux/amd64,或改用 x86 机器部署。
5. 任务跑到一半容器被 kill,日志里出现 OOMKilled
原因:内存不够,大仓库加测试进程很容易吃满。
```bash
docker inspect <容器名> --format '{{.State.OOMKilled}}'
free -h
```
解决:加内存或加 swap,同时在配置里调低并发任务数,别让多个任务同时跑。
后续维护
备份:需要备份的是数据卷和配置文件,代码仓库本身有远端不用管。
```bash
docker compose down
tar -czf backup-$(date +%F).tar.gz .env workspace/ <数据卷挂载目录>
```
.env 里有密钥,备份文件要加密存放,别扔在公共目录。
升级:升级前先看官方仓库的 Release Notes,注意环境变量有没有重命名、数据库有没有迁移脚本。
```bash
git pull
docker compose pull
docker compose up -d
docker compose logs -f --tail=200
```
升级后重跑一次第 7 步的验证任务,确认链路没断。
日志与监控:日常排查主要靠 docker compose logs。长期跑的话给 Docker 配上日志轮转,避免日志文件把磁盘写满(/etc/docker/daemon.json 里设 max-size 和 max-file)。监控重点看三个指标:任务成功率、单任务耗时、模型 token 消耗。token 消耗涨得离谱,通常是任务描述太模糊导致智能体反复试错,把任务拆小反而更省钱。
密钥轮换:PAT 和模型 API Key 定期更换,换完 docker compose up -d --force-recreate 生效。给智能体单独建一个机器人账号或用细粒度 token,权限只覆盖它需要动的仓库,出问题时好定位也好撤销。
