docs: clipboard requirements on linux

2 files changed, 42 insertions, 7 deletions

diff --git a/packages/tui/internal/clipboard/clipboard_linux.go b/packages/tui/internal/clipboard/clipboard_linux.go
index e65bdceab..5fdc1e7ad 100644
--- a/packages/tui/internal/clipboard/clipboard_linux.go
+++ b/packages/tui/internal/clipboard/clipboard_linux.go
@@ -79,7 +79,9 @@ func initialize() error {
 	}
 
 	if selectedTool < 0 {
-		slog.Warn("No clipboard utility found on system. Copy/paste functionality will be disabled.")
+		slog.Warn(
+			"No clipboard utility found on system. Copy/paste functionality will be disabled. See https://opencode.ai/docs/troubleshooting/ for more information.",
+		)
 		return fmt.Errorf(`%w: No clipboard utility found. Install one of the following:
 
 For X11 systems:
@@ -138,7 +140,8 @@ func readText(tool struct {
 			// xclip returns error when clipboard doesn't contain requested type
 			checkCmd := exec.Command("xclip", "-selection", "clipboard", "-t", "TARGETS", "-o")
 			targets, _ := checkCmd.Output()
-			if bytes.Contains(targets, []byte("image/png")) && !bytes.Contains(targets, []byte("UTF8_STRING")) {
+			if bytes.Contains(targets, []byte("image/png")) &&
+				!bytes.Contains(targets, []byte("UTF8_STRING")) {
 				return nil, errUnavailable
 			}
 		}
@@ -168,7 +171,8 @@ func readImage(tool struct {
 	}
 
 	// Verify it's PNG data
-	if len(out) < 8 || !bytes.Equal(out[:8], []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A}) {
+	if len(out) < 8 ||
+		!bytes.Equal(out[:8], []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A}) {
 		return nil, errUnavailable
 	}
 
diff --git a/packages/web/src/content/docs/docs/troubleshooting.mdx b/packages/web/src/content/docs/docs/troubleshooting.mdx
index 1fcd53fd8..8d0209846 100644
--- a/packages/web/src/content/docs/docs/troubleshooting.mdx
+++ b/packages/web/src/content/docs/docs/troubleshooting.mdx
@@ -43,17 +43,17 @@ This directory contains:
 If you're experiencing issues with opencode:
 
 1. **Report issues on GitHub**
-   
+
    The best way to report bugs or request features is through our GitHub repository:
-   
+
    [**github.com/sst/opencode/issues**](https://github.com/sst/opencode/issues)
-   
+
    Before creating a new issue, search existing issues to see if your problem has already been reported.
 
 2. **Join our Discord**
 
    For real-time help and community discussion, join our Discord server:
-   
+
    [**opencode.ai/discord**](https://opencode.ai/discord)
 
 ---
@@ -85,3 +85,34 @@ Here are some common issues and how to resolve them.
 1. Check that you've authenticated with the provider
 2. Verify the model name in your config is correct
 3. Some models may require specific access or subscriptions
+
+---
+
+### Copy/paste not working on Linux
+
+Linux users need to have one of the following clipboard utilities installed for copy/paste functionality to work:
+
+**For X11 systems:**
+
+```bash
+apt install -y xclip
+# or
+apt install -y xsel
+```
+
+**For Wayland systems:**
+
+```bash
+apt install -y wl-clipboard
+```
+
+**For headless environments:**
+
+```bash
+apt install -y xvfb
+# and run:
+Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
+export DISPLAY=:99.0
+```
+
+opencode will automatically detect and use the first available clipboard tool in order of preference: `xclip`, `xsel`, then `wl-clipboard`.