Mac Big Sur 使用 Docker 运行 OpenCode 实现 AI 自动化开发流程

注意：opencode server 命令是否存在？经查阅，opencode-ai 包确实包含一个服务模式（可通过 opencode server --help 确认）。如果你的版本没有，可改用 opencode api 或查看官方文档。若实在没有，也可通过 opencode 命令配合 --api 参数启动，但本文假设服务模式可用。

在 Dockerfile 所在目录下执行构建命令：

docker build -t opencode-server .

第二步：运行 OpenCode 容器

使用以下命令启动容器，并做好端口映射和目录挂载：

docker run -d \
  --name opencode-server \
  -p 36000:36000 \
  -v $(pwd):/workspace \
  --memory="2g" \
  --cpus="1.5" \
  opencode-server

参数说明：

• -d：后台运行。
• --name：指定容器名，方便后续操作。
• -p 36000:36000：将容器内 36000 端口映射到宿主机，供 OpenClaw 访问。
• -v $(pwd):/workspace：将当前目录挂载到容器的 /workspace，OpenCode 将在这个目录下读写代码。请确保在项目根目录执行此命令。
• --memory 和 --cpus：限制资源使用，避免容器耗尽宿主机性能。

运行后，检查容器状态：

docker ps

查看日志确认服务启动成功：

docker logs opencode-server

应该能看到类似 Server listening on http://0.0.0.0:36000 的输出。

第三步：验证 OpenCode 服务

在宿主机上执行以下 curl 命令，测试 API 是否可用（假设有健康检查端点）：

curl http://localhost:36000/health

如果返回 OK 或类似信息，说明服务已就绪。若没有 /health，可尝试其他端点如 /v1/models（模仿 OpenAI API 风格）。

第四步：配置 OpenClaw 使用 OpenCode 服务

OpenClaw 支持将 OpenCode 作为模型提供商。你可以通过环境变量或配置文件设置。

方法一：环境变量（临时生效）

export OPENCLAW_PRIMARY_MODEL=opencode/http://localhost:36000

方法二：修改配置文件 ~/.openclaw/openclaw.json

{"agents":{"defaults":{"model":{"primary":"opencode/http://localhost:36000"}}}}

完成后，可以通过一条简单指令测试连通性：

openclaw agent -m "你好，请问你能访问我的代码吗？"

如果 OpenClaw 能正常回复，说明与 OpenCode 的通信已建立。

第五步：安装 OpenSpec（如果尚未安装）

OpenSpec 是一个 npm 包，全局安装即可：

npm install -g @fission-ai/openspec@latest

进入你的项目目录，初始化 OpenSpec：

cd /path/to/your-project
openspec init

这会在项目根目录创建 openspec/ 文件夹，用于存放规范文档。

第六步：实战演练——让 AI 自动为代码添加日志功能

现在我们来模拟一个真实场景：为一个 Python 脚本添加详细的日志记录。

1. 用 OpenSpec 创建变更规范

openspec change new add-logging

该命令会在 openspec/changes/add-logging/ 下生成若干模板文件。我们主要编辑 tasks.md，将需求拆解为 AI 可执行的任务清单：

# Tasks: Add Logging to Script
## 1. 分析现有代码
- [ ] 1.1 读取 `src/app.py` 文件，找出所有函数入口和关键逻辑位置
## 2. 引入 logging 模块
- [ ] 2.1 在文件开头添加 `import logging`
- [ ] 2.2 配置基本日志格式（时间、级别、消息）
## 3. 添加日志语句
- [ ] 3.1 在每个函数入口添加 `logging.info(f"Entering {function_name}")`
- [ ] 3.2 在函数返回前添加 `logging.info(f"Exiting {function_name}")`
- [ ] 3.3 在异常处理处添加 `logging.error` 记录错误
## 4. 测试运行
- [ ] 4.1 运行脚本，确认日志正常输出

2. 通过 OpenClaw 下达作战指令

在 OpenClaw 的终端界面（或通过其 API）执行 sessions_spawn 命令，让它根据 tasks.md 自动完成所有任务：

sessions_spawn task:"严格按照 openspec/changes/add-logging/tasks.md 的步骤，为项目添加日志功能" label:"auto-add-logging" timeoutSeconds:300

OpenClaw 会启动一个后台任务，并将每一步的指令发给 OpenCode 执行。

3. 实时监控进度

你可以随时查看任务执行状态：

sessions_history sessionKey:"agent:main:subagent:auto-add-logging" limit:20

输出会显示每个子任务的完成情况，例如：

[DONE] 任务 1.1: 读取 src/app.py 文件
[DONE] 任务 2.1: 添加 import logging
[DONE] 任务 2.2: 配置日志格式
...
[ALL DONE] 所有任务已完成

4. 验证结果

打开 src/app.py，你会发现 AI 已经自动插入了日志代码，并且格式规范。运行脚本，日志如期输出。

第七步：资源控制与容器管理

为了避免 Docker 容器长期占用过多资源，你可以随时调整：

• 暂停容器：docker pause opencode-server
• 恢复容器：docker unpause opencode-server
• 停止容器：docker stop opencode-server
• 启动已停止的容器：docker start opencode-server
• 删除容器：docker rm opencode-server（如需重新创建）

如果你需要永久性限制资源，可以在 docker run 时使用 --memory 和 --cpus 参数，如上文所示。

总结：老系统也能玩转 AI 自动化开发

通过 Docker 容器化运行 OpenCode，我们成功绕过了 macOS Big Sur 的系统兼容性问题，使 OpenClaw、OpenCode 和 OpenSpec 能够无缝协作。现在，即使你的 Mac 停留在旧版本，也能体验前沿的 AI 自动化开发流程。

这套方案的优点在于：

• 隔离性：不污染宿主机环境，容器内的一切与系统无关。
• 可移植性：同样的容器可以在任何支持 Docker 的平台上运行。
• 资源可控：通过参数限制，容器不会成为资源大户。

当然，如果你更喜欢原生体验，也可以尝试从源码编译 OpenCode，但那需要解决一系列构建依赖，成功率因人而异。Docker 方案是目前最稳妥、最快捷的途径。

附录：可能遇到的问题及解决

1. opencode server 命令不存在怎么办？
   请运行 opencode --help 查看所有可用命令。如果没有 server，可以尝试 opencode api 或 opencode serve。如果确实没有服务模式，你可以采用另一种集成方式：在容器内直接运行 opencode 命令，并通过 docker exec 从宿主机调用（需要 OpenClaw 配合 shell 技能）。本文限于篇幅不再展开。
2. API 连接失败怎么办？
   • 检查容器是否正常运行：docker ps
   • 确认端口映射正确：docker port opencode-server
   • 在容器内测试服务是否监听：docker exec opencode-server curl http://localhost:36000/health（如果容器内有 curl）
3. OpenSpec 生成的 tasks.md 如何让 OpenClaw 正确解析？
   请参考 OpenClaw 官方文档关于 sessions_spawn 的用法，确保任务描述清晰，必要时可增加项目上下文。

权限问题：OpenCode 无法修改挂载的文件
容器内运行的用户可能不是 root，导致对宿主机文件没有写入权限。解决方法：在 docker run 时指定用户 ID 与宿主机一致：

docker run -d --user $(id -u):$(id -g)...

但需确保容器内存在该用户，或使用 root 用户（不推荐安全场景）。