OpenHands

环境要求

• Docker：macOS/Windows 用 Docker Desktop，Linux 用 Docker Engine 或 Docker Desktop
• 一个用于存放项目的宿主目录（对应 PROJECTS_PATH），需在启动容器前创建
• 宿主机上的 $HOME/.openhands 目录用于持久化配置（README 的启动命令会挂载它）
• Windows 用户需参考仓库中的 README.windows.md 使用等价命令

安装与启动步骤

1. 1安装并启动 Docker

   在 macOS/Windows 安装 Docker Desktop 并启动；Linux 安装 Docker Engine 或 Docker Desktop，确保 docker 命令可用。

2. 2设置项目路径变量

   设置 PROJECTS_PATH 指向存放你要让智能体访问的项目文件夹的上级目录，例如 $HOME/projects。

   export PROJECTS_PATH="$HOME/projects"

   复制

3. 3创建所需目录

   先创建 PROJECTS_PATH 目录和 $HOME/.openhands 目录，否则挂载可能报错或权限异常。

   mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

   复制

4. 4启动 Agent Canvas 容器

   映射 8000 端口，挂载配置目录与项目目录，拉取并运行官方镜像，容器退出后自动删除。

   docker run -it --rm 
     -p 8000:8000 
     -v "$HOME/.openhands:/home/openhands/.openhands" 
     -v "${PROJECTS_PATH}:/projects" 
     ghcr.io/openhands/agent-canvas:1.18.0

   复制

关键配置

如何确认成功

容器正常启动且不退出，宿主 8000 端口已映射，浏览器访问 http://localhost:8000 能看到 Agent Canvas 前端界面。

常见问题

注意事项

• 项目当前状态为 beta，接口与行为可能变化。
• 同一套 Agent Canvas 前端可切换本地、远程、云端多种后端环境，适合团队共享 Agent Server。
• 生产或公网部署前务必阅读 docs/SELF_HOSTING.md 中的安全加固说明。
• 镜像 tag 为 1.18.0，如需升级请改用其他版本 tag。