官方docs:Windows (WSL) | OpenCode

Settings
#

Proxy
#

打开WSL运行直接curl -fsSL https://opencode.ai/install | bash来安装opencode;

如果网络不好,可以临时配置WSL代理端口,然后重新输入: curl -fsSL https://opencode.ai/install | bash

我使用的是windows clashverge的混合端口; 要查看Clash Verge端口比如是7890; 先运行ip route，获取your_host_ip; 然后执行:

1export http_proxy="http://your_host_ip:7890"
2export https_proxy="http://your_host_ip:7890"

用curl ipinfo.io检查是否配置成功后重新安装opencode 显示下载完成后; 先刷新一下配置source ~/.bashrc ,然后运行opencode --help; 如果有输出就是安装成功啦;

为了解决网络问题可以考虑给WSL永久配置上Windows的代理;(其实临时更好) 先检查Clash Verge里的端口，比如混合端口是7890：

1nano ~/.bashrc # 进入配置页面

在配置页面最后加上如下内容

1# 自动获取 Windows Host IP  
2HOST_IP=$(ip route | awk '/default/ {print $3}')  
3# HTTP / HTTPS Proxy
4export http_proxy="http://$HOST_IP:7890"  
5export https_proxy="http://$HOST_IP:7890"  
6# SOCKS5 Proxy（按 Clash 实际端口修改）  
7export all_proxy="socks5://$HOST_IP:7898"

加载配置

1source ~/.bashrc

简单测试:

1env | grep proxy # 有输出对应变量即可

重装Ubuntu
#

出现难以解决的问题可以考虑

重装第一步
#

彻底删除旧的Ubuntu;

1wsl --unregister Ubuntu

重新安装Ubuntu: 可以直接点击任务栏Ubuntu图标很快就会自动重装需要重新设置用户名和密码然后先更新软件包

1sudo apt update
2sudo apt upgrade -y
3sudo apt autoremove -y

换源
#

个人认为不必要切换root用户,先换源就好

先备份配置文件

1sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

再更改国内镜像源:(参考) 先打开配置文件

1sudo nano /etc/apt/sources.list

将编辑器内内容替换为下面的内容(仅供参考)

 1# 清华大学开源软件镜像站 - Ubuntu 22.04 LTS (Jammy)
 2# 官方帮助文档：https://mirrors.tuna.tsinghua.edu.cn/help/ubuntu/
 3deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
 4# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
 5deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
 6# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
 7deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
 8# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse
 9deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
10# deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
11# 以下为可选：Proposed（预发布更新，一般不建议启用）
12# deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-proposed main restricted universe multiverse
13# # deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-proposed main restricted universe multiverse

注意自己Ubuntu的版本版本不同源也不同; 最后运行;

1sudo apt update

输出没有报错即可; 也可以使用脚本bash <(curl -sSL https://linuxmirrors.cn/main.sh)直接完成换源配置但是是黑盒;

env
#

优化环境变量,运行下图命令,(可选)

在echo $PATH测试后发现我的WSL由于继承windows环境变量后污染严重; 决定关闭继承; 因此:

1sudo nano /etc/wsl.conf

在最后写入:

1[interop]
2enabled = true
3appendWindowsPath = false

然后按Ctrl+O写入,再按Enter,最后按Ctrl+X退出即可最后可以运行source ~/.bashrc让配置立即生效或者在windows的Powershell里输入;

1wsl --shutdown

再重启WSL; 再在WSL内测试echo $PATH 就干净很多了;

安装nodejs
#

推荐先装nvm:

1curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

然后source ~/.bashrc加载配置，检测nvm --version; 接着安装稳定版nodejs:

1nvm install --lts

最后用nvm ls,node -v,npm -v检测是否安装成功;

备份Ubuntu
#

在确认当前Ubuntu环境配置相对干净后,可以导出一个备份;

在windows打开终端:

1wsl -l -v #复制输出的完整Ubuntu名称 
2wsl --shutdown #先关闭wsl

然后先建立好你想保存备份的文件夹; 最后运行下面指令即可

1wsl --export YOUR_UBUNTU_NAME D:\wsl_backup\ubuntu_snapshot.tar #示例路径

备份时若出现U盘不支持单次大文件的传输：右键U盘-属性-查看是否为FAT32; 如果是的话，先对U盘内已有文件进行备份，准备格式化; 右键U盘-格式化-格式一般选择exFAT-分配单元文件大小:保持默认即可; 完成后重新将Ubuntu备份复制进去就行;

Use
#

project area
#

在WSL终端操作Windows项目:

1cd /mnt/c/Users/YourName/project
2opencode

全部在WSL内工作:(性能更好)

1cd ~
2mkdir opencode_projects
3cd opencode_projects
4mkdir test
5cd test
6opencode

opencode functions
#

/timeline-选择对话记录-revert undo messages and file changes; 将对话和代码回退到当时状态重新修改;(WSL内文件不可回退);
/share-对话链接自动进入粘贴板-浏览器打开链接可分享,/unshare关闭链接;
/export将对话导出为文件;
/undo撤销操作可多次进行这个可能比较有用;
/session管理当前文件下的历史会话记录

AGENTS.md
#

按上图配置AGENTS.md即可; 不过优先考虑通过改变工程架构来提升agent能力;

skills
#

全局skill user/.config/opencode/skills/各个skill文件
项目skill project/.opencode/skills/各个skill文件 可以在opencode中输入/skill检查有无安装成功
优质社区:SkillHub-专为中国用户优化的Skills社区

MCP
#

具体配置一般写在user/.config/opencode/opencode.json中示例:(shadcn,context7)

 1{
"$schema": "https://opencode.ai/config.json",
"mcp": {
  "shadcn": {
    "type": "local",
    "command": [
      "npx",
      "-y",
      "shadcn@latest",
      "mcp"
    ],
    "enabled": true
  },
  "context7": {
    "type": "remote",
    "url": "https://mcp.context7.com/mcp",
    "enabled": true,
    "headers": {
      "CONTEXT7_API_KEY": "YOUR_API_KEY"
    }
  }
}
23}

来源1:Context7 - Up-to-date documentation for LLMs and AI code editors; 来源2:MCP Server - shadcn/ui

LCP
#

plugins
#

Oh My Opencode: (如果有claude订阅，codex，Go等订阅更加推荐)

1Install and configure oh-my-opencode by following the instructions here:
2https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

将以上prompt发给opencode 按照提示安装即可; 来源:code-yeongyu/oh-my-openagent: omo; the best agent harness - previously oh-my-opencode

OpenCode 会话记录与目录绑定
#

现象
#

如果： cd 某个子目录
opencode 则当前 session 很可能绑定到：

当前工作目录（cwd）
absolute path（绝对路径）
workspace path

当你之后：

修改子目录名称
移动目录
更换挂载路径会导致：
进入新目录后找不到旧会话
但在上级目录还能看到旧 session

推荐开发习惯
#

不要在深层子目录启动 opencode
#

错误示例：

1cd project/backend  
2opencode

先想好项目结构再开发
#

后期再修改项目结构就会使opencode会话记录与结构绑定失效

最佳实践
#

固定 project root
#

例如： my_project/ 尽量：

不改名
不移动但内部： src/
backend/
frontend/
docs/ 都可以自由修改。

如果已经改名导致 session 丢失
#

方法1
#

改回原目录名。 session 通常会恢复。

方法2
#

从项目根目录启动：

1cd project_root  
2opencode

不要直接进入改名后的子目录启动。

总结
#

推荐固定： project_root/ 然后永远： cd project_root
opencode

Settings#

Proxy#

重装Ubuntu#

重装第一步#

换源#

env#

安装nodejs#

备份Ubuntu#

Use#

project area#

opencode functions#

AGENTS.md#

skills#

MCP#

LCP#

plugins#

OpenCode 会话记录与目录绑定#

现象#

推荐开发习惯#

不要在深层子目录启动 opencode#

先想好项目结构再开发#

最佳实践#

固定 project root#

如果已经改名导致 session 丢失#

方法1#

方法2#

总结#