OpenCode CLI + Oh-My-OpenCode 入门指南

小米里的大麦2025-12-252026-02-15

Windows 上安装配置 OpenCode CLI + Oh-My-OpenCode 入门指南

1. 介绍

OpenCode CLI - 开源的 AI 编程助手命令行工具，类似 Cursor/Claude Code，但完全免费开源，支持多模型切换。

Oh-My-OpenCode - OpenCode 的增强插件，提供更智能的代理系统（Sisyphus 等），自动任务 orchestration，内置工具集。

总而言之，装了这个组合，就有了一个免费的 AI 编程团队。

2. 安装步骤（Windows）

1. 前置要求

Windows 10/11
Node.js 18+（已安装 npm）
网络能访问 GitHub

2. 安装 OpenCode CLI

# 用 npm 全局安装
npm i -g opencode-ai

# 或用 curl 一键安装
curl -fsSL https://opencode.ai/install | bash

# 验证安装
opencode --version

3. 安装 Oh-My-OpenCode 插件

# 全局安装最新稳定版
npm install -g oh-my-opencode@latest

# 运行安装向导
oh-my-opencode install

安装时会询问订阅情况，全部选 NO 即可使用免费模式。

4. 验证安装

1 2	opencode --version oh-my-opencode --version

3. 升级更新

# 升级 OpenCode CLI
npm update -g opencode-ai

# 升级 Oh-My-OpenCode 插件
npm update -g oh-my-opencode

# 查看版本
opencode --version
oh-my-opencode --version

4. 零订阅免费配置

没有 ChatGPT/Claude/Gemini/Copilot 订阅？没关系，使用免费模型。

1. 配置文件位置

1	C:\Users\<你的用户名>\.config\opencode\oh-my-opencode.json

2. 免费配置示例

重要提示：实测 opencode/glm-4.7-free 模型只有以下 4 个角色可用，其他角色配置后无法正常调用。

{
  // JSON Schema验证，提供智能提示和自动补全
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  
  // 代理模型配置
  // 实测：只有这4个角色支持 glm-4.7-free
  "agents": {
    "atlas": { "model": "opencode/glm-4.7-free" },         // 可用 - 总协调者(Plan Executor)
    "sisyphus": { "model": "opencode/glm-4.7-free" },       // 可用 - 超级工作者(ultraworker)
    "hephaestus": { "model": "opencode/glm-4.7-free" },     // 可用 - 深度代理(Deep Agent)
    "prometheus": { "model": "opencode/glm-4.7-free" }      // 可用 - 计划构建者(Plan Builder)
  },
  
  // 分类模型配置
  // 所有分类都用免费模型
  "categories": {
    "visual-engineering": { "model": "opencode/glm-4.7-free" },      // 前端/UI任务
    "ultrabrain": { "model": "opencode/glm-4.7-free" },              // 高难度逻辑任务
    "deep": { "model": "opencode/glm-4.7-free" },                    // 深度研究任务
    "artistry": { "model": "opencode/glm-4.7-free" },                // 创意任务
    "quick": { "model": "opencode/glm-4.7-free" },                   // 简单快速任务
    "unspecified-low": { "model": "opencode/glm-4.7-free" },         // 低复杂度未分类任务
    "unspecified-high": { "model": "opencode/glm-4.7-free" },        // 高复杂度未分类任务
    "writing": { "model": "opencode/glm-4.7-free" }                  // 文档写作任务
  },
  
  // 技能模块配置
  // 启用内置专业技能模块
  "skills": {
    "playwright": { "enabled": true },      // 浏览器自动化：网页爬取、截图、测试
    "git-master": { "enabled": true },      // Git专家：原子提交、rebase、分支管理
    "frontend-ui-ux": { "enabled": true },  // 前端设计：无设计稿也能做UI
    "dev-browser": { "enabled": true }      // 浏览器调试：页面状态持久化
  },
  
  // MCP外部工具配置
  // 启用内置MCP服务，扩展AI能力
  "mcp": {
    "websearch": { "enabled": true },       // 网页搜索：获取最新信息
    "context7": { "enabled": true },        // 文档查询：查官方API文档
    "grep_app": { "enabled": true }         // GitHub搜索：找开源实现示例
  },
  
  // Hooks自动检查配置
  // 启用自动化质量检查
  "hooks": {
    "todo-continuation": { "enabled": true },  // TODO强制执行：任务没完成会继续
    "comment-checker": { "enabled": true }     // 注释检查：防止AI生成过多注释
  }
}

3. 其他免费/低成本配置选项

如需使用更多角色，可申请以下 API（均有免费额度）：

提供商	模型名	特点	注册地址
DeepSeek	`deepseek-chat`	代码能力强，价格便宜	platform.deepseek.com
Kimi	`kimi-k2.5`	长上下文支持	platform.moonshot.cn
MiniMax	`minimax-2.1`	中文优化好	platform.minimaxi.com

1. DeepSeek 配置步骤

# 1. 注册获取API Key：https://platform.deepseek.com

# 2. 配置环境变量（系统环境变量）
setx DEEPSEEK_API_KEY "your-api-key-here"

# 3. 重启终端，使环境变量生效

# 4. 在 oh-my-opencode.json 中配置
{
  "agents": {
    "sisyphus": { "model": "deepseek/deepseek-chat" },
    "hephaestus": { "model": "deepseek/deepseek-chat" },
    "prometheus": { "model": "deepseek/deepseek-chat" },
    "atlas": { "model": "deepseek/deepseek-chat" },
    "oracle": { "model": "deepseek/deepseek-chat" },      // DeepSeek支持
    "librarian": { "model": "deepseek/deepseek-chat" },   // DeepSeek支持
    "explore": { "model": "deepseek/deepseek-chat" }      // DeepSeek支持
  }
}

2. Kimi (Moonshot) 配置步骤

# 1. 注册获取API Key：https://platform.moonshot.cn

# 2. 配置环境变量
setx MOONSHOT_API_KEY "your-api-key-here"

# 3. 重启终端

# 4. 在 oh-my-opencode.json 中配置
{
  "agents": {
    "sisyphus": { "model": "kimi/k2.5" },
    "hephaestus": { "model": "kimi/k2.5" },
    "oracle": { "model": "kimi/k2.5" },
    "librarian": { "model": "kimi/k2.5" }
  }
}

3. MiniMax 配置步骤

# 1. 注册获取API Key：https://minimax.chat

# 2. 配置环境变量
setx MINIMAX_API_KEY "your-api-key-here"

# 3. 重启终端

# 4. 在 oh-my-opencode.json 中配置
{
  "agents": {
    "sisyphus": { "model": "minimax/2.1" },
    "hephaestus": { "model": "minimax/2.1" }
  }
}

5. OpenCode CLI 基础使用

1. 启动

# 在当前目录启动
opencode

# 指定目录启动
opencode D:\my-project

2. 常用命令

命令	作用
`/exit` 或 `Ctrl+C`	退出
`/clear`	清空对话
`/models`	查看可用模型
`/model <模型名>`	切换模型
`/agents`	查看代理列表
`/start-work`	执行 Prometheus 创建的计划
`/handoff`	保存会话上下文

3. 快捷操作

Tab 键 - 触发 Prometheus 规划模式
↑↓ 方向键 - 浏览历史命令
Ctrl+R - 搜索历史

6. Ultrawork 超级工作模式

什么是 Ultrawork？

在提示中包含 ultrawork 或 ulw 关键词，即可触发 最强模式。所有功能自动启用：

并行代理执行
后台任务处理
深度代码库探索
不懈执行直到 100% 完成

使用示例：

1
2
3

你：ulw 帮我重构这个项目的登录模块
Atlas：自动协调 → 分配任务给 Sisyphus
Sisyphus：分析 → 编码 → 测试 → 验证 → 完成

只要加 ulw，其他交给系统 —— AI 会自动判断、协调、完成。

7. Oh-My-OpenCode 核心角色详解（v3.6.0）

免费套餐只能用这 4 个角色，无需任何 API Key，开箱即用。

1. 4 个免费角色一览

角色	英文名	干什么的	什么时候用
Atlas	Plan Executor	总指挥，协调所有代理	用 `ulw` 时自动启用
Sisyphus	ultraworker	主力执行，写代码干活	日常开发任务
Hephaestus	Deep Agent	深度攻坚，处理复杂任务	架构重构、技术难题
Prometheus	Plan Builder	先规划，再动手	复杂任务前期分析

2. Atlas (Plan Executor)

一句话：总指挥，不写代码，只负责协调和验证。

怎么触发：输入 ulw 或 ultrawork 自动启用。

实际工作流程：

你：ulw 帮我实现用户管理系统

Atlas 自动：
1. 分析任务 → 判断复杂度
2. 调用 Prometheus → 制定计划
3. 分配任务 → Sisyphus/Hephaestus 执行
4. 验证结果 → 确保完成
5. 交付给你

你不需要管 Atlas，它会自动工作。只要记住 ulw 这个魔法词。

3. Sisyphus (ultraworker)

一句话：主力干活的，处理 80% 的日常开发任务。

适合场景：

修复 Bug
实现功能
代码重构
写测试

怎么用：

1 2	直接说：帮我实现登录功能或者：ulw 修复这个 bug

实际效果：

你：帮我实现登录功能

Sisyphus：
1. 找到相关代码
2. 写登录逻辑
3. 跑测试
4. 确认能用
5. 完成

特点：边做边调整，灵活快速，是主力执行者。

4. Hephaestus (Deep Agent)

一句话：处理复杂任务的，先探索再动手，不做到位不罢休。

适合场景：

架构重构
技术债务清理
复杂功能实现
需要大量分析的任务

怎么用：

1 2	你：ulw 重构这个项目的架构或者：用 Hephaestus 模式处理这个复杂任务

实际效果：

你：ulw 重构项目架构

Hephaestus：
1. 先全面探索代码库
2. 分析问题和依赖
3. 制定重构方案
4. 端到端实现
5. 验证通过
6. 完成

vs Sisyphus：

	Sisyphus	Hephaestus
适合	日常任务	复杂任务
方式	边做边调	先探索再动手
速度	快	深入

5. Prometheus (Plan Builder)

一句话：先规划再动手，不写代码，只输出计划。

适合场景：

任务复杂，不知道从哪开始
需求不明确
想先看计划再决定

怎么用：

1 2	按 Tab 键或者：帮我规划一下这个需求

实际效果：

你：按 Tab 键

Prometheus：
1. 问你几个问题（技术栈？功能范围？）
2. 分析隐含需求
3. 输出任务清单（比如 12 个任务）
4. 等你确认

你：/start-work
Sisyphus：按计划执行

特点：只规划不写代码，输出任务清单让你确认。

6. 4 个角色怎么配合？

简单理解：

Atlas = 总指挥（自动协调）
Prometheus = 先规划（Tab 键触发）
Sisyphus = 干活（日常任务）
Hephaestus = 攻坚（复杂任务）

实际协作流程：

你：ulw 帮我做一个完整的用户管理系统

1. Atlas 自动启动
2. Atlas 调用 Prometheus 制定计划
3. Prometheus 输出任务清单
4. Atlas 分配任务：
   - 简单任务 → Sisyphus
   - 复杂任务 → Hephaestus
5. 执行完成
6. Atlas 验证
7. 交付给你

记住：只要加 ulw，其他交给系统自动处理。

7. 其他角色（需要 API Key）

免费套餐只能用上面 4 个。其他角色可能需要配置 API Key：

角色	干什么的	需要
Oracle	解决诡异 Bug、架构决策	API Key
Librarian	查官方文档、搜开源代码	API Key
Explore	快速搜索代码库	API Key
Metis	分析需求合理性	API Key
Momus	评估计划质量	API Key

现实情况：4 个免费角色已经够用，覆盖 95% 场景。如需更多，申请 DeepSeek API（有免费额度）。

8. 示例配置

如果你还是不知道如何配置，可以参考我的配置：

1. `opencode.json` 配置

{
  "plugin": [
    "oh-my-opencode@latest"
  ],
  "$schema": "https://opencode.ai/config.json",
  "skills": {
    "paths": [
      "C:\\Users\\Huangcancan\\.config\\opencode\\skills"
    ]
  },
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@playwright/mcp@latest"
      ],
      "enabled": true,
      "timeout": 20000
    },
    "open_websearch": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "open-websearch@latest"
      ],
      "enabled": true,
      "timeout": 120000
    },
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app",
      "enabled": true,
      "oauth": false,
      "timeout": 10000
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true,
      "oauth": false,
      "timeout": 10000
    },
    "mcp_everything": {
      "type": "local",
      "command": [
        "npx",
        "@modelcontextprotocol/server-everything"
      ],
      "enabled": true,
      "timeout": 10000
    },
    "chrome_devtools": {
      "type": "local",
      "command": [
        "npx",
        "chrome-devtools-mcp"
      ],
      "enabled": true,
      "timeout": 10000
    }
  }
}

2. `oh-my-opencode.json` 配置

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "hephaestus": {
      "model": "opencode/glm-4.7-free",
      "variant": "medium"
    },
    "oracle": {
      "model": "opencode/glm-4.7-free",
      "variant": "high"
    },
    "librarian": {
      "model": "opencode/glm-4.7-free"
    },
    "explore": {
      "model": "opencode/glm-4.7-free"
    },
    "multimodal-looker": {
      "model": "opencode/glm-4.7-free"
    },
    "prometheus": {
      "model": "opencode/glm-4.7-free",
      "variant": "high"
    },
    "metis": {
      "model": "opencode/glm-4.7-free",
      "variant": "high"
    },
    "momus": {
      "model": "opencode/glm-4.7-free",
      "variant": "medium"
    },
    "atlas": {
      "model": "opencode/glm-4.7-free"
    }
  },
  "categories": {
    "visual-engineering": {
      "model": "opencode/glm-4.7-free"
    },
    "ultrabrain": {
      "model": "opencode/glm-4.7-free",
      "variant": "xhigh"
    },
    "deep": {
      "model": "opencode/glm-4.7-free",
      "variant": "medium"
    },
    "quick": {
      "model": "opencode/glm-4.7-free"
    },
    "unspecified-low": {
      "model": "opencode/glm-4.7-free",
      "variant": "medium"
    },
    "unspecified-high": {
      "model": "opencode/glm-4.7-free",
      "variant": "medium"
    },
    "writing": {
      "model": "opencode/glm-4.7-free"
    },
    "artistry": {
      "model": "opencode/glm-4.7-free"
    }
  }
}

9. 实际使用示例

1. 快速修复 Bug

1 2	你：修复登录功能的bug Sisyphus：自动 → 搜索相关代码 → 分析 → 修复 → 测试

2. 复杂功能开发

你：ultrawork 帮我实现一个完整的用户管理系统
Atlas：
  1. 调用 Prometheus 制定计划
  2. 协调 Sisyphus 和 Hephaestus 执行
  3. 验证所有任务完成
  4. 交付成果

3. 规划复杂任务

你：按Tab键
Prometheus：访谈需求 → 创建计划 → 输出任务列表
你：/start-work
Sisyphus：按计划执行

4. 深度重构

1
2
3

你：ulw 重构这个遗留项目的架构
Atlas：判断复杂度 → 协调 Hephaestus 深度执行
Hephaestus：探索代码库 → 制定重构策略 → 端到端执行 → 验证交付

10. 结语

装完这套工具，就拥有了一个 7×24 小时在线的 AI 编程团队。

核心记住这 4 个免费角色：

Atlas (Plan Executor) - 总指挥，协调一切
Sisyphus (ultraworker) - 超级工作者，主力执行
Hephaestus (Deep Agent) - 深度代理，攻坚专家
Prometheus (Plan Builder) - 计划构建者，先规划再执行

这 4 个角色完全免费，无需任何 API Key，开箱即用，已覆盖 95% 的开发场景。

记住魔法词：ulw —— 加入 ulw，让 AI 为你工作。

Windows 上安装配置 OpenCode CLI + Oh-My-OpenCode 入门指南

1. 介绍

2. 安装步骤（Windows）

1. 前置要求

2. 安装 OpenCode CLI

3. 安装 Oh-My-OpenCode 插件

4. 验证安装

3. 升级更新

4. 零订阅免费配置

1. 配置文件位置

2. 免费配置示例

3. 其他免费/低成本配置选项

1. DeepSeek 配置步骤

2. Kimi (Moonshot) 配置步骤

3. MiniMax 配置步骤

5. OpenCode CLI 基础使用

1. 启动

2. 常用命令

3. 快捷操作

6. Ultrawork 超级工作模式

什么是 Ultrawork？

7. Oh-My-OpenCode 核心角色详解（v3.6.0）

1. 4 个免费角色一览

2. Atlas (Plan Executor)

3. Sisyphus (ultraworker)

4. Hephaestus (Deep Agent)

5. Prometheus (Plan Builder)

6. 4 个角色怎么配合？

7. 其他角色（需要 API Key）

8. 示例配置

1. opencode.json 配置

2. oh-my-opencode.json 配置

9. 实际使用示例

1. 快速修复 Bug

2. 复杂功能开发

3. 规划复杂任务

4. 深度重构

10. 结语

小米里的大麦

1. `opencode.json` 配置

2. `oh-my-opencode.json` 配置