Open file references from Codex output directly in VS Code or Cursor with file_opener
How the file_opener setting in Codex CLI turns cited file paths into clickable editor links: the values (vscode, vscode-insiders, windsurf, cursor, none) and terminal requirements.
When Codex says it changed src/auth/session.ts:42, hunting for that file in your editor each time is tedious. Codex CLI has a file_opener setting that turns such references into links that open the file in your editor.
In short: put file_opener = "cursor" or another editor name in ~/.codex/config.toml, and file references in the output become links using that editor's URI scheme. The default is vscode.
KEY POINT
What you will learn
- The five accepted values and the default
- What your terminal needs for the links to work
- Turning it off, and situations such as SSH where it does not help
The values
file_opener = "cursor"| Value | Editor |
|---|---|
vscode (default) | Visual Studio Code |
vscode-insiders | VS Code Insiders |
windsurf | Windsurf |
cursor | Cursor |
none | no links |
The docs describe the setting as converting file citations into clickable URI-scheme links for supported editors. For VS Code that is the vscode://file/<absolute path>:<line>:<column> form, which jumps to the line when clicked.
用語解説
URI scheme: an address form such as vscode:// or cursor:// that launches an application directly. The OS maps the scheme to the app, so clicking the link opens that editor.
What it needs to work
- A terminal with hyperlink (OSC 8) support: iTerm2, WezTerm, Windows Terminal, Kitty, and recent GNOME Terminal among others
- The chosen editor installed locally with its URI scheme registered
- Codex running locally. Over SSH, the link points at a path on the remote host, which your local editor cannot open
If you run Codex inside VS Code's integrated terminal, keeping file_opener = "vscode" opens files in the same window.
The IDE extension has its own mechanism
file_opener is a CLI (terminal) setting. The Codex extensions for VS Code and Cursor show diffs and navigate to files through the extension's own UI.
Turning it off and related settings
To stop link conversion, set none.
file_opener = "none"Several nearby [tui] settings affect display and combine well with it.
| Key | Default | Meaning |
|---|---|---|
tui.theme | unset | syntax-highlighting theme |
tui.alternate_screen | auto | use the alternate screen (auto / always / never) |
tui.animations | true | terminal animations |
tui.raw_output_mode | false | start in raw scrollback mode |
Reducing reasoning output to make the transcript easier to read is covered in Hiding reasoning in Codex output. The overall config file structure is in the hub article Configuring Codex with config.toml.
Summary
file_openerturns file references into editor URI links; values arevscode(default),vscode-insiders,windsurf,cursor,none- It needs OSC 8 hyperlink support in the terminal and a registered URI scheme for the editor
- Links from Codex running over SSH do not open locally
- The IDE extensions navigate through their own UI, so treat this as a CLI setting
- Combine with
[tui]theme, alternate screen, and animation settings
FAQ
- What is the default for file_opener?
- vscode. Even without setting it, file references become VS Code links in a supporting terminal.
- I use Cursor.
- Set file_opener = "cursor". windsurf and vscode-insiders are also available.
- The references show as plain text, not links.
- Your terminal needs hyperlink (OSC 8) support. Terminals without it show the URI or no link at all.
Primary sources
This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.