如何用 Docker Desktop 在 Windows 或 macOS 本地运行 Archon 并打开 Web UI【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon在 Windows 或 macOS 上想不依赖 VPS 和域名直接用 Docker Desktop 把 Archon 跑起来然后在浏览器里打开它的 Web UI。官方部署文档中的Local Docker Desktop (Windows / macOS)路径正好覆盖这个场景不需要域名、不需要 VPS数据库默认使用 SQLite零配置Web UI 地址是http://localhost:3000。这条路径的前提机器上已安装 Docker Desktop含 Docker Compose已安装 Git至少准备一组 AI 凭据CLAUDE_CODE_OAUTH_TOKEN或CLAUDE_API_KEY。Docker 容器内没有本地claudeCLI因此CLAUDE_USE_GLOBAL_AUTHtrue在 Docker 中不可用必须显式提供其中一项。OAuth token 可以在本地机器上运行claude setup-token获取。获取代码并配置 .envArchon 的docker-compose.yml通过build: .从仓库源码构建镜像所以需要先把仓库克隆到本地git clone https://gitcode.com/GitHub_Trending/archon3/Archon cd Archon cp .env.example .env然后编辑.env设置 AI 凭据二选一# 方式 AClaude OAuth token本地运行 claude setup-token 获取 CLAUDE_CODE_OAUTH_TOKENsk-ant-oat01-xxxxx # 方式 BClaude API key # CLAUDE_API_KEYsk-ant-xxxxx仓库根目录的 .env.example 带有完整的变量注释平台适配器 tokenTelegram、Slack 等都是可选的本地单机使用可以全部留空。启动容器并打开 Web UI在仓库根目录执行docker compose up -d首次运行会构建镜像官方 Dockerfile 为三阶段构建deps → web-build → production需要等待一段时间。默认不带 profile 启动时只启动app一个容器数据库使用 SQLite文件存放在 Docker 管理的archon_data卷里无需任何数据库配置。启动后有两种验证方式浏览器打开http://localhost:3000应看到 Archon Web UI命令行检查健康端点Docker 环境使用/api/health不是/healthcurl http://localhost:3000/api/health也可以用docker compose ps确认容器状态。本地 Docker Desktop 部署的能力范围官方文档标注为特性状态Web UIhttp://localhost:3000数据库SQLite自动零配置HTTPS / Caddy本地不需要认证无单用户仅 localhost平台适配器可选Telegram、Slack 等Windows从 WSL 构建而不是 PowerShellWindows 上有两个已知问题都发生在构建/启动阶段1. 构建上下文报错The file cannot be accessed by the system。原因是 Docker Desktop on Windows 在传输构建上下文时无法跟随 Bun workspace 的符号链接。解决办法是在 WSL 终端里执行而不是 PowerShellcd /mnt/c/Users/YourName/path/to/Archon docker compose up -d其中/mnt/c/Users/YourName/path/to/Archon需要替换为你在 Windows 上的实际仓库路径WSL 中 C 盘挂载在/mnt/c下。2. 行尾错误exec docker-entrypoint.sh: no such file or directory。仓库通过.gitattributes强制 shell 脚本使用 LF 行尾。如果你的克隆发生在该规则加入之前脚本会带 CRLF 行尾导致容器无法启动。文档给出的修复方式是重新克隆或者git rm --cached -r . git reset --hardmacOS默认卷可直接用bind mount 需要额外注意默认情况下数据存放在 Docker 管理的命名卷archon_data和archon_user_home中macOS 上直接docker compose up -d即可不需要额外操作。如果你想在.env中用ARCHON_DATA把数据目录指到主机上的具体路径bind mountmacOS 上要注意Docker Desktop 的 VirtioFS 挂载由宿主系统控制文件属主容器 entrypoint 每次启动时把/.archon属主修复为appuserUID 1001的操作一定会失败容器会以退出码 1 终止并反复重启。此时文档给出的显式开关是在.env中设置ARCHON_ALLOW_ROOT_FALLBACK1需要明确这是一个有安全代价的选项容器会以 root 身份运行不再降权到appuser同时设置IS_SANDBOX1AI 子进程也以 root 运行。文档认为它只适用于单操作员的 macOS 开发机这类绑定挂载已经限定了容器可触达范围的场景它永远不会被自动启用。可选本地 PostgreSQLSQLite 足够本地起步使用如果想在本地也用 PostgreSQL用with-dbprofile 启动并在.env中补上连接串主机名必须用 Docker 服务名postgres不是localhostdocker compose --profile with-db up -dDATABASE_URLpostgresql://postgres:postgrespostgres:5432/remote_coding_agentschema 在首次启动时自动初始化无需手动执行 psql。文档同时提醒如果用了--profile with-db却没有设置DATABASE_URL应用会回退到 SQLite 并记录一条警告PostgreSQL 容器会运行但不会被使用。数据持久化与停止容器内所有数据workspace、worktree、artifact、日志、SQLite 库都在/.archon/默认映射到archon_data卷~/.claude/、~/.gitconfig等用户态文件在archon_user_home卷中容器重建后依然保留。docker compose down停止容器数据保留docker compose down -v会同时删除卷属于破坏性操作文档中明确标注 destructive不要在保留数据的情况下执行。常见问题应用起不来日志出现no_ai_credentials没有配置任何 AI 助手。回到.env确认CLAUDE_CODE_OAUTH_TOKEN或CLAUDE_API_KEY已设置且值有效。端口被占用Docker 部署默认端口是3000docker-compose.yml中为${PORT:-3000}本地开发模式默认是 3090两者不冲突。如果 3000 被占用在.env中改端口PORT3001然后按新端口访问 Web UI。容器反复重启docker compose ps docker compose logs --tail50 app文档列出的常见原因是缺少.env文件、凭据无效、数据库不可达。健康检查请求失败确认请求的是http://localhost:3000/api/health。Docker 环境与健康检查都用/api/health/health是本地开发模式的便捷别名。后续操作停止服务docker compose down数据保留。更新版本git pull后重新docker compose up -d --build。需要 HTTPS、Caddy 反向代理、Basic Auth 或 GitHub Webhook 时那属于--profile cloud的服务器部署路径需要域名和 DNS A 记录不在本地 Docker Desktop 场景内可参见文档中的 Server 章节deployment/docker.md。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考