📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,152 @@
|
||||
---
|
||||
name: codex-config
|
||||
description: This skill should be used when configuring Codex CLI, setting up profiles, or when "config.toml", "sandbox mode", "Codex config", or "approval policy" are mentioned.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
related-skills:
|
||||
- claude-config
|
||||
- skills-dev
|
||||
---
|
||||
|
||||
# Codex Configuration Management
|
||||
|
||||
Manages configuration files for OpenAI Codex CLI, including model settings, sandbox policies, MCP servers, and profiles.
|
||||
|
||||
## Configuration Location
|
||||
|
||||
**Primary Config:** `~/.codex/config.toml`
|
||||
|
||||
**Skills Paths (precedence, highest first):**
|
||||
1. `$CWD/.codex/skills/` - Current directory
|
||||
2. `$CWD/../.codex/skills/` - Parent directory
|
||||
3. `$REPO_ROOT/.codex/skills/` - Repository root
|
||||
4. `~/.codex/skills/` - User-level
|
||||
5. `/etc/codex/skills/` - System/admin level
|
||||
6. Built-in skills - Bundled with Codex
|
||||
|
||||
## Basic config.toml
|
||||
|
||||
```toml
|
||||
# Model settings
|
||||
model = "gpt-5.2-codex"
|
||||
model_verbosity = "medium" # high | medium | low
|
||||
model_reasoning_effort = "high" # low | high | xhigh
|
||||
|
||||
# Permissions
|
||||
approval_policy = "on-failure" # untrusted | on-failure | on-request | never
|
||||
sandbox_mode = "workspace-write" # read-only | workspace-write | danger-full-access
|
||||
exec_timeout_ms = 300000 # 5 minutes
|
||||
|
||||
# Misc
|
||||
file_opener = "cursor" # Editor for opening files
|
||||
```
|
||||
|
||||
## Profiles
|
||||
|
||||
Define named profiles for different workflows:
|
||||
|
||||
```toml
|
||||
[profiles.max]
|
||||
model = "gpt-5.1-codex-max"
|
||||
model_verbosity = "high"
|
||||
model_reasoning_effort = "xhigh"
|
||||
|
||||
[profiles.fast]
|
||||
model = "gpt-5.1-codex-mini"
|
||||
model_verbosity = "low"
|
||||
model_reasoning_effort = "low"
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
codex -p max "complex refactoring task"
|
||||
codex -p fast "quick fix"
|
||||
```
|
||||
|
||||
## MCP Servers
|
||||
|
||||
```toml
|
||||
[mcp_servers.server-name]
|
||||
command = "npx"
|
||||
args = ["-y", "@package/mcp-server"]
|
||||
enabled = true
|
||||
tool_timeout_sec = 60.0
|
||||
|
||||
[mcp_servers.server-name.env]
|
||||
API_KEY = "your-key"
|
||||
```
|
||||
|
||||
## Skills
|
||||
|
||||
### Invoking Skills
|
||||
|
||||
```bash
|
||||
# Explicit invocation
|
||||
codex "$plan implement authentication"
|
||||
codex "$skill-creator new skill for testing"
|
||||
|
||||
# Implicit (Codex decides based on context)
|
||||
codex "plan out the implementation"
|
||||
```
|
||||
|
||||
### Built-in Skills
|
||||
|
||||
- `$plan` - Research and create implementation plans
|
||||
- `$skill-creator` - Bootstrap new skills
|
||||
- `$skill-installer` - Download skills from GitHub
|
||||
|
||||
## CLI Override
|
||||
|
||||
Override any config value at runtime:
|
||||
|
||||
```bash
|
||||
codex -c model="o3"
|
||||
codex -c 'sandbox_permissions=["disk-full-read-access"]'
|
||||
codex -c shell_environment_policy.inherit=all
|
||||
```
|
||||
|
||||
## Convenience Flags
|
||||
|
||||
| Flag | Equivalent |
|
||||
|------|------------|
|
||||
| `--full-auto` | `-a on-request --sandbox workspace-write` |
|
||||
| `--oss` | `-c model_provider=oss` (local LM Studio/Ollama) |
|
||||
| `--search` | Enable web search tool |
|
||||
|
||||
```bash
|
||||
codex --full-auto "implement feature"
|
||||
codex -C /path/to/project "work in different dir"
|
||||
codex --add-dir /additional/path "access multiple dirs"
|
||||
```
|
||||
|
||||
## Quick Validation
|
||||
|
||||
```bash
|
||||
# Check TOML syntax
|
||||
cat ~/.codex/config.toml | toml-lint
|
||||
|
||||
# Test config override
|
||||
codex -c model="test" --help
|
||||
|
||||
# Verify MCP servers
|
||||
codex mcp list
|
||||
```
|
||||
|
||||
## Quick Troubleshooting
|
||||
|
||||
**Config not loading:** Verify `~/.codex/config.toml` exists, check TOML syntax
|
||||
|
||||
**MCP server not connecting:** Check command path, verify API keys, check `enabled = true`
|
||||
|
||||
**Skills not found:** Verify path hierarchy, check SKILL.md exists in skill folder
|
||||
|
||||
**Sandbox too restrictive:** Use `-s workspace-write`, check project trust level
|
||||
|
||||
## References
|
||||
|
||||
Detailed documentation for specific scenarios:
|
||||
|
||||
- **[MCP Servers](references/mcp-servers.md)** - Server configuration examples (Context7, Firecrawl, Graphite, Linear)
|
||||
- **[Troubleshooting](references/troubleshooting.md)** - Common issues, debug commands, validation
|
||||
- **[Security](references/security.md)** - Sandbox modes, approval policies, trust levels, best practices
|
||||
@@ -0,0 +1,138 @@
|
||||
# MCP Server Configuration for Codex
|
||||
|
||||
Detailed examples and patterns for configuring MCP servers in Codex CLI.
|
||||
|
||||
## Basic Structure
|
||||
|
||||
```toml
|
||||
[mcp_servers.server-name]
|
||||
command = "npx"
|
||||
args = ["-y", "@package/mcp-server"]
|
||||
enabled = true
|
||||
tool_timeout_sec = 60.0
|
||||
|
||||
[mcp_servers.server-name.env]
|
||||
API_KEY = "your-key"
|
||||
```
|
||||
|
||||
## Common MCP Servers
|
||||
|
||||
### Context7 (Documentation Lookup)
|
||||
|
||||
```toml
|
||||
[mcp_servers.context7]
|
||||
command = "npx"
|
||||
args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_KEY"]
|
||||
```
|
||||
|
||||
### Firecrawl (Web Scraping)
|
||||
|
||||
```toml
|
||||
[mcp_servers.firecrawl]
|
||||
command = "npx"
|
||||
args = ["-y", "firecrawl-mcp"]
|
||||
|
||||
[mcp_servers.firecrawl.env]
|
||||
FIRECRAWL_API_KEY = "YOUR_KEY"
|
||||
```
|
||||
|
||||
### Graphite (Stacked PRs)
|
||||
|
||||
```toml
|
||||
[mcp_servers.graphite]
|
||||
command = "gt"
|
||||
args = ["mcp"]
|
||||
```
|
||||
|
||||
### Linear (Project Management)
|
||||
|
||||
```toml
|
||||
[mcp_servers.linear]
|
||||
command = "npx"
|
||||
args = ["-y", "mcp-remote@latest", "https://mcp.linear.app/sse"]
|
||||
```
|
||||
|
||||
### PostgreSQL
|
||||
|
||||
```toml
|
||||
[mcp_servers.postgres]
|
||||
command = "npx"
|
||||
args = ["-y", "@modelcontextprotocol/server-postgres"]
|
||||
|
||||
[mcp_servers.postgres.env]
|
||||
POSTGRES_CONNECTION_STRING = "postgresql://localhost/mydb"
|
||||
```
|
||||
|
||||
### Filesystem
|
||||
|
||||
```toml
|
||||
[mcp_servers.filesystem]
|
||||
command = "npx"
|
||||
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Timeout Settings
|
||||
|
||||
```toml
|
||||
[mcp_servers.slow-server]
|
||||
command = "slow-command"
|
||||
args = []
|
||||
tool_timeout_sec = 120.0 # 2 minutes
|
||||
```
|
||||
|
||||
### Disabling Servers
|
||||
|
||||
```toml
|
||||
[mcp_servers.disabled-server]
|
||||
command = "some-command"
|
||||
args = []
|
||||
enabled = false
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```toml
|
||||
[mcp_servers.custom-server.env]
|
||||
API_KEY = "secret"
|
||||
DEBUG = "true"
|
||||
HOME = "/custom/home"
|
||||
```
|
||||
|
||||
## Multiple Servers Example
|
||||
|
||||
```toml
|
||||
# Documentation
|
||||
[mcp_servers.context7]
|
||||
command = "npx"
|
||||
args = ["-y", "@upstash/context7-mcp"]
|
||||
|
||||
# Project management
|
||||
[mcp_servers.linear]
|
||||
command = "npx"
|
||||
args = ["-y", "mcp-remote@latest", "https://mcp.linear.app/sse"]
|
||||
|
||||
# Version control
|
||||
[mcp_servers.graphite]
|
||||
command = "gt"
|
||||
args = ["mcp"]
|
||||
|
||||
# Web scraping
|
||||
[mcp_servers.firecrawl]
|
||||
command = "npx"
|
||||
args = ["-y", "firecrawl-mcp"]
|
||||
|
||||
[mcp_servers.firecrawl.env]
|
||||
FIRECRAWL_API_KEY = "YOUR_KEY"
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
# List configured MCP servers
|
||||
codex mcp list
|
||||
|
||||
# Test specific server
|
||||
codex mcp test server-name
|
||||
```
|
||||
@@ -0,0 +1,148 @@
|
||||
# Security Configuration for Codex
|
||||
|
||||
Sandbox modes, approval policies, and security best practices.
|
||||
|
||||
## Sandbox Modes
|
||||
|
||||
| Mode | Description | Use Case |
|
||||
|------|-------------|----------|
|
||||
| `read-only` | No write access | Safe exploration, code review |
|
||||
| `workspace-write` | Write to workspace only | Normal development |
|
||||
| `danger-full-access` | Full system access | Trusted operations only |
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
codex -s read-only "analyze this codebase"
|
||||
codex -s workspace-write "implement feature"
|
||||
codex --dangerously-bypass-approvals-and-sandbox # EXTREME CAUTION
|
||||
```
|
||||
|
||||
### In Config
|
||||
|
||||
```toml
|
||||
sandbox_mode = "workspace-write" # Default for all sessions
|
||||
```
|
||||
|
||||
## Approval Policies
|
||||
|
||||
| Policy | Behavior |
|
||||
|--------|----------|
|
||||
| `untrusted` | Only trusted commands (ls, cat, sed) run without approval |
|
||||
| `on-failure` | All commands run; approval only if command fails |
|
||||
| `on-request` | Model decides when to ask |
|
||||
| `never` | Never ask for approval |
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
codex -a untrusted "careful task"
|
||||
codex -a never "automated pipeline"
|
||||
codex --full-auto # Alias for -a on-request --sandbox workspace-write
|
||||
```
|
||||
|
||||
### In Config
|
||||
|
||||
```toml
|
||||
approval_policy = "on-failure" # Balanced default
|
||||
```
|
||||
|
||||
## Project Trust Levels
|
||||
|
||||
Set trust levels per project:
|
||||
|
||||
```toml
|
||||
[projects]
|
||||
"/path/to/trusted/project" = { trust_level = "trusted" }
|
||||
"/path/to/another" = { trust_level = "trusted" }
|
||||
```
|
||||
|
||||
**Trust levels:**
|
||||
- `trusted` - Full permissions within sandbox
|
||||
- `untrusted` - Stricter command approval
|
||||
|
||||
## Shell Environment Policy
|
||||
|
||||
Control which environment variables are available:
|
||||
|
||||
```toml
|
||||
[shell_environment_policy]
|
||||
set = { MY_VAR = "value" } # Force-set environment vars
|
||||
inherit = "all" # all | core | none
|
||||
ignore_default_excludes = false
|
||||
include_only = [] # Whitelist patterns
|
||||
```
|
||||
|
||||
### Minimal Environment
|
||||
|
||||
```toml
|
||||
[shell_environment_policy]
|
||||
inherit = "core" # Only PATH, HOME, USER
|
||||
set = { CI = "true" }
|
||||
```
|
||||
|
||||
### Inherit Everything
|
||||
|
||||
```toml
|
||||
[shell_environment_policy]
|
||||
inherit = "all"
|
||||
```
|
||||
|
||||
### Whitelist Specific Variables
|
||||
|
||||
```toml
|
||||
[shell_environment_policy]
|
||||
inherit = "none"
|
||||
include_only = ["PATH", "HOME", "USER", "EDITOR", "TERM"]
|
||||
```
|
||||
|
||||
## Convenience Flags
|
||||
|
||||
| Flag | Equivalent |
|
||||
|------|------------|
|
||||
| `--full-auto` | `-a on-request --sandbox workspace-write` |
|
||||
| `-s read-only` | `--sandbox read-only` |
|
||||
| `-a never` | `--approval-policy never` |
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```toml
|
||||
# Recommended for most development
|
||||
sandbox_mode = "workspace-write"
|
||||
approval_policy = "on-failure"
|
||||
```
|
||||
|
||||
### CI/CD Pipelines
|
||||
|
||||
```toml
|
||||
# Fully automated
|
||||
sandbox_mode = "workspace-write"
|
||||
approval_policy = "never"
|
||||
```
|
||||
|
||||
### Code Review / Exploration
|
||||
|
||||
```toml
|
||||
# Read-only for safety
|
||||
sandbox_mode = "read-only"
|
||||
approval_policy = "untrusted"
|
||||
```
|
||||
|
||||
### Sensitive Operations
|
||||
|
||||
```bash
|
||||
# Explicit approval for everything
|
||||
codex -a untrusted -s read-only "security audit"
|
||||
```
|
||||
|
||||
## Security Checklist
|
||||
|
||||
- [ ] Use `workspace-write` as default sandbox
|
||||
- [ ] Set `approval_policy = "on-failure"` as baseline
|
||||
- [ ] Only use `danger-full-access` when absolutely necessary
|
||||
- [ ] Review project trust levels periodically
|
||||
- [ ] Don't store secrets in config.toml
|
||||
- [ ] Use environment variables for sensitive values
|
||||
- [ ] Review MCP server permissions before enabling
|
||||
@@ -0,0 +1,162 @@
|
||||
# Troubleshooting Codex Configuration
|
||||
|
||||
Common issues and solutions for Codex CLI configuration.
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Config Not Loading
|
||||
|
||||
**Symptoms:** Settings not applied, defaults used instead
|
||||
|
||||
**Solutions:**
|
||||
1. Verify `~/.codex/config.toml` exists
|
||||
2. Check TOML syntax
|
||||
3. Use `-c` to override and test
|
||||
|
||||
```bash
|
||||
# Test with override
|
||||
codex -c model="gpt-5.2" --help
|
||||
|
||||
# Validate TOML syntax
|
||||
cat ~/.codex/config.toml | toml-lint
|
||||
```
|
||||
|
||||
### MCP Server Not Connecting
|
||||
|
||||
**Symptoms:** Tools not available, connection errors
|
||||
|
||||
**Checklist:**
|
||||
1. Check command path is correct
|
||||
2. Verify API keys in env section
|
||||
3. Check `enabled = true`
|
||||
4. Review `tool_timeout_sec`
|
||||
|
||||
```bash
|
||||
# List servers and status
|
||||
codex mcp list
|
||||
|
||||
# Test server connection
|
||||
codex mcp test server-name
|
||||
```
|
||||
|
||||
### Skills Not Found
|
||||
|
||||
**Symptoms:** `$skill-name` not recognized
|
||||
|
||||
**Checklist:**
|
||||
1. Verify path hierarchy
|
||||
2. Check skill directory structure
|
||||
3. Ensure SKILL.md exists in skill folder
|
||||
|
||||
**Skills path precedence:**
|
||||
1. `$CWD/.codex/skills/`
|
||||
2. `$CWD/../.codex/skills/`
|
||||
3. `$REPO_ROOT/.codex/skills/`
|
||||
4. `~/.codex/skills/`
|
||||
5. `/etc/codex/skills/`
|
||||
6. Built-in skills
|
||||
|
||||
### Sandbox Too Restrictive
|
||||
|
||||
**Symptoms:** Permission denied, can't access files
|
||||
|
||||
**Solutions:**
|
||||
- Use `-s workspace-write` for normal development
|
||||
- Check project trust level
|
||||
- Consider `--add-dir` for additional paths
|
||||
|
||||
```bash
|
||||
# Add additional writable directory
|
||||
codex --add-dir /path/to/data "task requiring data access"
|
||||
|
||||
# Check current sandbox mode
|
||||
codex -c sandbox_mode
|
||||
```
|
||||
|
||||
## Debug Commands
|
||||
|
||||
### Check Current Configuration
|
||||
|
||||
```bash
|
||||
# View current features
|
||||
codex features
|
||||
|
||||
# Check effective config
|
||||
codex config show
|
||||
```
|
||||
|
||||
### Session Management
|
||||
|
||||
```bash
|
||||
# Resume previous session
|
||||
codex resume
|
||||
|
||||
# Resume last session
|
||||
codex resume --last
|
||||
|
||||
# List recent sessions
|
||||
codex sessions
|
||||
```
|
||||
|
||||
### Sandbox Debugging
|
||||
|
||||
```bash
|
||||
# Run command in sandbox debug mode
|
||||
codex sandbox <command>
|
||||
|
||||
# Check sandbox permissions
|
||||
codex sandbox --check
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
### TOML Syntax
|
||||
|
||||
```bash
|
||||
# Using toml-lint
|
||||
cat ~/.codex/config.toml | toml-lint
|
||||
|
||||
# Using Python
|
||||
python -c "import toml; toml.load(open('$HOME/.codex/config.toml'))"
|
||||
```
|
||||
|
||||
### Test Config Override
|
||||
|
||||
```bash
|
||||
# Test model setting
|
||||
codex -c model="gpt-5.2-codex" --help
|
||||
|
||||
# Test multiple settings
|
||||
codex -c model="gpt-5.2" -c model_verbosity="high" --help
|
||||
```
|
||||
|
||||
### Verify MCP Servers
|
||||
|
||||
```bash
|
||||
# List all configured servers
|
||||
codex mcp list
|
||||
|
||||
# Check specific server
|
||||
codex mcp test graphite
|
||||
```
|
||||
|
||||
## Log Locations
|
||||
|
||||
Codex logs are typically in:
|
||||
- `~/.codex/logs/` (if logging enabled)
|
||||
- System journal (on Linux with systemd)
|
||||
|
||||
## Reset Configuration
|
||||
|
||||
If configuration is corrupted:
|
||||
|
||||
```bash
|
||||
# Backup current config
|
||||
cp ~/.codex/config.toml ~/.codex/config.toml.bak
|
||||
|
||||
# Start fresh
|
||||
rm ~/.codex/config.toml
|
||||
|
||||
# Recreate with defaults
|
||||
codex config init
|
||||
```
|
||||
Reference in New Issue
Block a user