OpenCode：你的AI编程助手

paopao_wu2026-02-09 9:46

AI 辅助编程已成为提升效率的重要手段。OpenCode 作为一款开源的 AI 编程助手，正以其强大的功能和开源特性吸引着越来越多开发者的关注。

官方网站：https://opencode.ai/

1.安装前准备

OpenCode是一个开源的AI编程助手。它提供终端界面、桌面应用或IDE插件等多种形式。本文章以windows 终端界面为例对它进行介绍。

1.1 PowerShell终端（可选）

你也可以选择直接使用 windows上自带的命令行终端。这里推荐使用这个开源跨平台的终端获取更好的体验。

https://github.com/PowerShell/PowerShell

这个项目是 PowerShell 开源跨平台版本（即 PowerShell 7+）的官方核心代码库。它与 Windows 自带的"Windows PowerShell"既有历史渊源，又是两个完全独立发展的产品。

它是一个开源、跨平台（支持 Windows, Linux, macOS）的自动化和配置管理工具。

下载操作系统对应的版本：

安装完成后，会出现在右键菜单上。

1.2 使用npm安装

OpenCode 本身并不强制要求安装 Node.js，因为OpenCode 是一个用 Rust 语言编写的独立二进制工具。这意味着它的核心程序本身不需要 Node.js 环境来运行，但是如果你采用 npm命令来安装，那么你需要提前安装好 nodejs

shell 复制代码 
npm i -g opencode-ai
opencode --version
1.1.51

1.3 Chocolatey 安装

Chocolatey 是 Windows 平台上的命令行软件包管理器，类似于 macOS 上的 Homebrew 或 Linux 上的 apt/yum。它让 Windows 用户能够像在 Linux 中一样，通过简单的命令来安装、更新和管理软件。

Chocolatey CLI 又名 choco（或 choco.exe）是一个客户端（不是 Windows 服务），它提供 Chocolatey 的核心和本地安装包的安装存储。

shell 复制代码 
bash @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
shell 复制代码 
choco install opencode

opencode --version

如果安装了360等杀毒软件，要将文件加入到可信任区域（2个），否则会显示 "拒绝访问"

2.配置和初始化

新建文件夹，然后用PowerShell7 打开文件夹，输入命令 opencode启动 OpenCode：

2.1 配置LLM供应商

输入/connect命令，连接LLM供应商。

如果你使用的是windows自带的命令行工具，当输入API KEY 的时候如果发现无法粘贴，则需要配置一下命令行窗口

OpenCode 使用AI SDK和Models.dev来支持75 多家大语言模型提供商并支持运行本地模型。

您通过**/connect**命令添加了提供商的凭据，那么在您启动OpenCode时，这些提供商将可用。

OpenCode Zen 提供了一些免费的模型，后面有 Free字样，我们可以直接使用

Other -> xxx (China) 可以连接国内的模型提供商，其中有：

Moonshot AI （China）月之暗面

Zhipu AI 智普，

Alibaba(china) (阿里百炼)

2.2 选择模型

输入/models,就可以选择模型了。

连接成功后，提个问题：

2.3 初始化

对当前项目进行初始化。 在 OpenCode 的终端工具（TUI）中输入 /init 命令，这个命令会执行如下核心操作：

  1. 项目结构扫描： OpenCode 会递归扫描当前工作目录，识别项目中的文件层级、目录结构以及主要的技术栈。
  2. 生成 **AGENTS.md** 文件 ： 这是 /init 最关键的产出。它会在你的项目根目录下创建一个名为 AGENTS.md 的 Markdown 文件。这个文件相当于一份"项目说明书"或"上下文索引"，包含以下内容：
  • 项目概览：对项目的用途和功能的总结。
  • 文件地图：列出重要的文件和目录。
  • 编码规范与模式：分析项目中已有的代码风格和常用的编程模式，以便后续生成的代码能与现有代码保持一致。
  1. 建立上下文基准 ： 通过这个过程，OpenCode 将项目从"一堆零散的文件"转变为"可理解的整体上下文"。当你后续进行对话或请求修改代码时，它会优先参考 AGENTS.md 中的信息，从而提供更精准、更符合项目逻辑的建议。

3.关于AGENTS.md

在 OpenCode 的机制中，AGENTS.md 是 AI 代理在执行任务前必读的"宪法"。

  1. 上下文注入 ：当你提出需求时，OpenCode 会将 AGENTS.md 的内容作为 System Prompt 的一部分发送给大模型。
  2. 行为约束：明确的语言指令会覆盖模型默认的响应逻辑。

比如我希望模型输出的内容是中文，可以在 AGENTS.md末尾添加：

latex 复制代码 
## Language & Communication Preferences
- **Primary Language**: All responses, explanations, and comments generated by the AI must be in **Chinese (Simplified)**.
- **Output Policy**: Even if the codebase uses English (e.g., variable names, documentation), the dialogue and task descriptions provided by the agent must remain in Chinese.

4.基本命令

  • OpenCode 内置了两个核心代理（Agent），可以通过按 Tab 键在它们之间切换。
    • build: 这是默认的代理，拥有完整的开发权限，可以读取文件、写入代码以及执行命令。
    • plan: 这是一个只读的代理，用于分析代码和规划任务。它默认会拒绝修改文件，并在执行命令前征求许可，非常适合在探索不熟悉的代码库或规划复杂功能时使用。
  • TUI： 终端用户界面
    • 文件引用使用 @
    • 如果要在终端中执行 shell命令，则输入!进行切换， esc退回
复制代码 
- `/connect`连接模型提供商

选择 Alibaba China ,然后输入阿里百炼 API KEY

复制代码 
- `/compact`压缩会话
- `/exit`退出 `/quit``/q`
- `/models`列出有效的模型
- `/new`开始新会话
- `/redo``/undo` 使用git管理才能使用
- `/share`共享当前session
- `/thinking`打开或关闭思考过程是否显示

5.配置

关于配置文件，官方参考文档： https://opencode.ai/docs/config/

OpenCode 使用JSON文件作为配置。支持 JSON和 JSONC格式。JSONC格式中可以使用注释

配置文件可以放在多个地方，多个配置文件会合并，后面的key会覆盖前面的key

  • 远程配置：把配置放在网站上 **.well-known/opencode**
  • 全局配置: **~/.config/opencode/opencode.json** windows 在 用户主目录下的 .config文件夹中
  • **自定义环境变量配置 ****OPENCODE_CONFIG**
  • **项目配置 ****opencode.json**
  • **.opencode**目录，包含 **agents**, **commands**, **plugins**

5.1 连接Ollama

假如Ollama所在的服务器地址为 ：192.168.6.133， 端口为 11434

5.1.1 准备ollama 模型

  1. 检查服务器上的Ollama版本:
shell 复制代码 
# 输出为 0.15.6
ollama -v
ollama version is 0.15.6

这个版本提供了对 OpenCode 的支持：

  1. 在运行 OpenCode 的机器上能访问: http://192.168.6.133:11434/v1/models ,如果服务可用，则会返回 Ollama中已经pull下来的模型
  2. 下载模型

接下来使用最新的 qwen3-coder-next:cloud和 glm-ocr

shell 复制代码 
ollama pull qwen3-coder-next:cloud
ollama pull glm-ocr:latest

ollama list
NAME                        ID              SIZE      
glm-ocr:latest              6effedd0dc8a    2.2 GB    
qwen3-coder-next:cloud      aa626c11ae8d    -
  1. 因为要使用 cloud模型，所以需要登录ollama账号
shell 复制代码 
ollama signin

5.1.2 配置open code

ollama 官方给出了配置文档： https://docs.ollama.com/integrations/opencode

  1. 编辑全局配置文件：~/.config/opencode/opencode.json,不存在就创建一个。 ~是home目录
  2. 添加配置
json 复制代码 
{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen3-coder-next:cloud",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://192.168.6.133:11434/v1"
      },
      "models": {
        "glm-ocr:latest": {
          "name": "glm-ocr:latest"
        },
        "qwen3-coder-next:cloud": {
          "name": "qwen3-coder-next:cloud"
        }
      }
    }
  }
}

model 指定了默认模型为 ollama/qwen3-coder-next:cloud

models 中的key是 opencode 内部识别模型的标识， 而 name 字段是发送给 ollama api的模型名称，必须与 ollama 的模型ID完全一致。

为了保持简单和避免混淆，建议让 key 和 name 保持一致，都使用 Ollama 的实际模型 ID。

  1. 再次启动 opencode ,发现默认的模型已经变成了 wen3-coder-next:cloud

5.2 opencode服务配置

可以作为web服务器运行

shell 复制代码 
opencode web --port 4096 --hostname 0.0.0.0

 Local access:        http://localhost:4096
 Network access:      http://192.168.6.120:4096

也可以在配置文件opencode.json中做配置：

json 复制代码 
{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0"
  }
}

6.AgentSkills

Skills，中文叫"技能包"，是一套告诉AI遇到特定任务该怎么做的说明书。放在约定目录里、带有固定 YAML 头（frontmatter）的 SKILL.md 文件，用来给 OpenCode 的 agent 提供"可复用的行为/指令"。OpenCode 会自动发现这些技能，并在 agent 需要时通过 skill 工具按需加载。

6.1 SKILL.md的位置

位置 文件
项目配置 .opencode/skills//SKILL.md
全局配置 ~/.config/opencode/skills//SKILL.md

6.2 SKILL.md 规范

它是一个Markdown文件， 可以用任何文本编辑器、Markdown 阅读器打开它。

如果没有那个 YAML 头，它就只是一个普通的说明文档，OpenCode 的 Agent 不会把它当作可执行的"技能"来加载。它不是随意写的，是有规范的：

  • **name** (required)**name**（必填）
  • **description** (required)**description**（必填）
  • **license** (optional)**license**（可选）
  • **compatibility** (optional)**compatibility**（可选）
  • **metadata** (optional, string-to-string map)**metadata**（可选，字符串到字符串映射）

每一个 SKILL.md 必须在文件最开始用两行 --- 包围一段 YAML，像这样：

yaml 复制代码 
---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

然后再接 Markdown 正文（## What I do / ## When to use me 等）。

下面是一个完整的例子：

yaml 复制代码 
---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---
## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me
Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

name 必须和目录名一致

目录 .opencode/skills/git-release/SKILL.md, 则name必须是 ： git-release

6.3 加载机制

Skills 采用渐进式加载，不是一股脑全塞给AI，而是分层按需加载：

层级 内容 加载时机 大小建议
L1 name + description 始终在上下文 ~100词
L2 SKILL.md 正文 技能触发时 <5000词
L3 scripts/references/assets 按需加载 不限

6.4 触发匹配逻辑

关键在于 description 字段------每个Skill都有一个描述，写明"什么时候用这个技能"。

所以，description写得好不好，直接决定Skill能不能被正确触发。

latex 复制代码 
你说："帮我整理下今天的AI新闻"
      ↓
AI扫描所有Skill的description
      ↓
匹配到 searchnews（描述里包含"整理新闻"、"AI新闻"）     
      ↓
加载这个Skill，按流程执行
内容类型 Token消耗 原因
SKILL.md正文 占用上下文 AI要看内容，属于提示词
scripts/脚本 不占上下文 AI只是调用执行
references/参考 不占上下文 AI按需读取，用完即弃

6.5 获取可重用的skills

获取可重用的 OpenCode Skills（技能）主要有三种途径：官方/社区仓库、第三方市场、以及兼容生态（如 Claude Code）。

由于 OpenCode 遵循 Agent Skills 开放标准，它与 Anthropic 的 Claude Code 技能高度通用，这极大地扩展了可用的资源池。

  • 官方与权威社区仓库
名称 地址 技能
Anthropic 官方 Skills 库 github.com/anthropics/skills frontend-design（前端设计）、skill-creator（自动生成新技能）、docx/pdf/xlsx（文档处理）
OpenCode Awesome 列表 github.com/awesome-opencode/awesome-opencode 包含插件、主题和各种特定场景的技能。
Awesome OpenClaw Skills github.com/VoltAgent/awesome-openclaw-skills docker-essentials、debug-pro（系统调试）、code-mentor（代码导师）。
  • 技能市场 (Marketplaces)
    • 地址 ：skills.sh
    • 操作 ：支持一键安装。例如使用命令 npx skills add <owner/repo> 即可快速集成。
    • 热门项 ：agent-tools、agent-browser（增强网页浏览能力）。
  • 推荐
技能名称 功能描述 推荐理由
Skill Creator 自动编写新技能的技能 授人以渔。你只需描述需求，它会帮你写好符合规范的 SKILL.md 。
Frontend Design UI/UX 审美增强 让 AI 生成的代码不仅仅能跑，还能"好看"，符合现代设计规范。
Debug Pro 深度调试助手 提供系统化的排查思路，针对不同编程语言有专门的调试策略。
Project Memory 项目记忆增强 自动维护项目的上下文信息，减少 AI 在长对话中"失忆"的情况。
Superpowers 综合能力增强包 集成了脑暴、需求文档编写、测试用例生成等全流程工具。
相关推荐
智算菩萨8 小时前
【Generative AI For Autonomous Driving】1 生成式AI重塑自动驾驶的技术浪潮与体系化挑战
论文阅读·人工智能·深度学习·机器学习·ai·自动驾驶
智算菩萨8 小时前
【Generative AI For Autonomous Driving】7 生成式AI驱动自动驾驶的未来图景：开放挑战、社会机遇与技术展望
论文阅读·人工智能·深度学习·机器学习·ai·自动驾驶
王菜鸟9 小时前
什么是Agent及相关框架介绍
ai·ai编程
AI英德西牛仔9 小时前
deepseek怎么导出文档
人工智能·ai·chatgpt·deepseek·ds随心转
wywppkd9 小时前
Claude Code 快速上手
ai编程·claude
HIT_Weston9 小时前
21、【Agent】【OpenCode】源码构建（项目构建）
人工智能·agent·opencode
SoRound9 小时前
OpenClaw 实现原理详解（六）：WebSocket Gateway 详解
ai编程
samson_www9 小时前
千问伴我部署Dify
ai
楚国的小隐士9 小时前
“你用AI，那我也会用AI，我还要你干什么？”
ai·大模型·编程·ai编程·哲学·氛围编程·辩证唯物主义·马列主义·唯物论
左耳咚9 小时前
Claude Code 中的 SubAgent
前端·ai编程·claude
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06OpenClaw 使用和管理 MCP 完全指南07UV安装并设置国内源08“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）09OpenClaw Control UI安全上下文访问配置10Labelme从安装到标注：零基础完整指南