opencode-agent

🏠 Home / Docs / WSL2 / Opencode / opencode-agent.md
目录

官方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; 然后执行:

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

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

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

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

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

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

加载配置

source ~/.bashrc

简单测试:

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

重装Ubuntu

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

重装第一步

彻底删除旧的Ubuntu;

wsl --unregister Ubuntu

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

sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y

换源

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

先备份配置文件

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

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

sudo nano /etc/apt/sources.list

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

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

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

sudo apt update

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

env

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

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

sudo nano /etc/wsl.conf

在最后写入:

[interop]
enabled = true
appendWindowsPath = false

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

wsl --shutdown

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

安装nodejs

推荐先装nvm:

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

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

nvm install --lts

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

备份Ubuntu

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

在windows打开终端:

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

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

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

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

Use

project area

在WSL终端操作Windows项目:

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

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

cd ~
mkdir opencode_projects
cd opencode_projects
mkdir test
cd test
opencode

opencode functions

AGENTS.md

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

skills

MCP

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

{
  "$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"
      }
    }
  }
}

来源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等订阅 更加推荐)

Install and configure oh-my-opencode by following the instructions here:
https://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

错误示例：

cd project/backend  
opencode

推荐：

cd project_root  
opencode

之后：

这样 session 更稳定。

先想好项目结构再开发

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

最佳实践

固定 project root

例如： my_project/ 尽量： - 不改名 - 不移动 但内部： src/
backend/
frontend/
docs/ 都可以自由修改。

如果已经改名导致 session 丢失

方法1

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

方法2

从项目根目录启动：

cd project_root  
opencode

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

总结

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