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 综合能力增强包 集成了脑暴、需求文档编写、测试用例生成等全流程工具。
相关推荐
Jastep5 小时前
Dify本地化部署
ai·dify
回眸&啤酒鸭5 小时前
【回眸】AI新鲜事（二）使用Copilot制定一个60天的系统学习AI计划细化落实到每天并导入Outlook日程？
ai·outlook
AI_56785 小时前
阿里云OSS成本优化：生命周期规则+分层存储省70%
运维·数据库·人工智能·ai
猫头虎5 小时前
OpenClaw开源汉化发行版：介绍、下载、安装、配置教程
运维·windows·开源·aigc·ai编程·agi·csdn
天燹6 小时前
OpenClaw (Clawdbot) Windows 平台本地化一键部署实践
ai
小邓睡不饱耶6 小时前
实战｜W餐饮平台智能化菜品推荐方案（含Spark实操+算法选型+完整流程）
python·ai·ai编程·ai写作
飞哥数智坊6 小时前
TRAE Friends@济南第3场圆满落幕，一次技术平权的具象化冲击
ai编程·trae
寻星探路12 小时前
【深度长文】万字攻克网络原理：从 HTTP 报文解构到 HTTPS 终极加密逻辑
java·开发语言·网络·python·http·ai·https
一切尽在，你来16 小时前
第二章 预告内容
人工智能·langchain·ai编程
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03openclaw配置教程（linux+局域网ollama）04UV安装并设置国内源05Linux下V2Ray安装配置指南06AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南07Claude Code Skills 实用使用手册08OpenClaw Chrome扩展使用教程 - 浏览器中继控制09Vue-skills的中文文档10openclaw使用nginx反代部署过程 与disconnected (1008): pairing required解决