ai-coding-agents

AI 编码 Agent 技能

Codex CLI 和 Claude Code CLI 的专业知识——两款领先的 AI 编码 Agent。

**注意：**本技能介绍这两款工具，供参考。VMark 开发主要使用 Claude Code CLI。为确保内容完整并支持跨工具工作流，此处保留 Codex CLI 相关部分。

适用场景

• 通过 CLI 编排复杂编码任务
• 为任一工具配置 MCP 服务
• 设置自动化流水线（CI/CD）
• 排查身份验证或沙盒问题
• 比较不同 Agent 的能力
• 配置自定义 Agent/子 Agent

快速参考

启动会话

任务	Codex CLI	Claude Code CLI
交互式会话	codex	claude
使用提示词	codex "fix the bug"	claude "fix the bug"
非交互模式	codex exec "task"	claude -p "task"
恢复上一个会话	codex resume --last	claude -c
按 ID 恢复	codex resume <id>	claude -r <id>

安全模式

模式	Codex CLI	Claude Code CLI
只读	-s read-only	--permission-mode plan
工作区写入	-s workspace-write	（默认）
完全访问	-s danger-full-access	--dangerously-skip-permissions
自动模式	--full-auto	--permission-mode default
YOLO 模式	--yolo	--dangerously-skip-permissions

模型选择

任务	Codex CLI	Claude Code CLI
选择模型	-m gpt-5-codex	--model opus
使用本地 OSS	--oss	N/A
后备模型	N/A	--fallback-model sonnet

---

Codex CLI（OpenAI）

安装

npm i -g @openai/codex
# or
brew install --cask codex

身份验证

codex login              # OAuth via ChatGPT
codex login --with-api-key   # Read API key from stdin
codex login status       # Check auth status
codex logout             # Remove credentials

核心命令

codex - 交互模式

codex                           # Start TUI
codex "fix all TypeScript errors"  # With initial prompt
codex -i screenshot.png "explain"  # With image
codex --full-auto "refactor"    # Low-friction mode
codex --search "find docs"      # Enable web search

codex exec - 非交互模式

codex exec "write tests"        # Run and exit
codex e "task"                  # Short alias
echo "task" | codex exec -      # From stdin
codex exec --json "task"        # JSONL output
codex exec -o result.txt "task" # Save to file
codex exec --output-schema schema.json "task"  # Validate output

codex resume - 继续会话

codex resume                    # Interactive picker
codex resume --last             # Most recent
codex resume --all              # Show all (any directory)
codex resume <session-id>       # Specific session
codex resume <id> "continue with this"  # With prompt

codex review - 代码审查

codex review                    # Review current branch vs main
codex review --uncommitted      # Review uncommitted changes
codex review --base develop     # Against specific branch
codex review --commit abc123    # Review specific commit
codex review "focus on security"  # Custom instructions

codex apply - 应用云任务

codex apply <task-id>           # Apply diff from cloud task

codex cloud - 云任务（实验性）

codex cloud                     # Browse cloud tasks
codex cloud exec "task" --env <env-id>  # Submit task
codex cloud status <task-id>    # Check status
codex cloud diff <task-id>      # Show diff
codex cloud apply <task-id>     # Apply changes

codex mcp - MCP 服务管理

codex mcp list                  # List servers
codex mcp list --json           # JSON output
codex mcp get <name>            # Server details
codex mcp add <name> -- npx my-server   # Add stdio server
codex mcp add <name> --url https://... # Add HTTP server
codex mcp add <name> --env API_KEY=xxx -- cmd  # With env vars
codex mcp remove <name>         # Remove server
codex mcp login <name> --scopes read,write  # OAuth for HTTP
codex mcp logout <name>         # Remove OAuth

codex sandbox - 运行沙盒命令

# macOS
codex sandbox macos -- npm test
codex sandbox seatbelt --full-auto -- ./script.sh

# Linux
codex sandbox linux -- npm test
codex sandbox landlock -- ./script.sh

codex completion - Shell 自动补全

codex completion bash >> ~/.bashrc
codex completion zsh >> ~/.zshrc
codex completion fish > ~/.config/fish/completions/codex.fish

斜杠命令（交互模式）

命令	用途
/model	切换模型（gpt-5-codex、gpt-5 等）
/approvals	更改审批策略
/compact	总结对话，释放上下文
/diff	显示 git diff
/review	分析工作树
/status	显示配置和令牌用量
/mcp	列出可用的 MCP 工具
/mention	附加文件
/fork	分支对话
/resume	重新打开之前的会话
/new	开始新对话
/init	创建 AGENTS.md 脚手架
/feedback	提交日志/诊断信息
/quit、/exit	退出 CLI

配置（~/.codex/config.toml）

model = "gpt-5-codex"
approval_policy = "on-request"

[sandbox]
mode = "workspace-write"

[features]
web_search = true

[profiles.ci]
model = "gpt-4.1"
approval_policy = "never"

全局标志

-m, --model <MODEL>          Model selection
-s, --sandbox <MODE>         read-only|workspace-write|danger-full-access
-a, --ask-for-approval <P>   untrusted|on-failure|on-request|never
-c, --config <KEY=VALUE>     Override config
-C, --cd <DIR>               Working directory
-i, --image <FILE>           Attach image(s)
-p, --profile <NAME>         Config profile
--full-auto                  Low-friction mode
--yolo                       Bypass all safety (DANGEROUS)
--search                     Enable web search
--add-dir <DIR>              Grant additional write access
--enable <FEATURE>           Enable feature flag
--disable <FEATURE>          Disable feature flag
--oss                        Use local OSS model

---

Claude Code CLI（Anthropic）

安装

npm install -g @anthropic-ai/claude-code

身份验证

claude                      # First run prompts login
claude setup-token          # Set up long-lived token
# Requires Claude Pro/Max subscription OR API key

核心命令

claude - 交互模式

claude                          # Start REPL
claude "explain this project"   # With prompt
claude -c                       # Continue last conversation
claude -r "session-name"        # Resume by name/ID
claude --model opus             # Select model
claude --chrome                 # Enable Chrome integration
claude --ide                    # Auto-connect to IDE

claude -p - 打印模式（非交互）

claude -p "explain this function"   # Query and exit
cat file | claude -p "explain"      # Process piped input
claude -p --output-format json "q"  # JSON output
claude -p --output-format stream-json "q"  # Streaming JSON
claude -p --max-turns 3 "task"      # Limit agent turns
claude -p --max-budget-usd 5 "task" # Spending limit
claude -p --json-schema '{...}' "q" # Validate output schema

claude mcp - MCP 服务管理

claude mcp list                 # List servers
claude mcp get <name>           # Server details
claude mcp add <name> <cmd>     # Add stdio server
claude mcp add -t http <name> <url>  # Add HTTP server
claude mcp add -e KEY=val <name> -- cmd  # With env vars
claude mcp add -H "Auth: Bearer x" <name> <url>  # With headers
claude mcp add -s project <name> <cmd>  # Project scope
claude mcp remove <name>        # Remove server
claude mcp serve                # Run as MCP server
claude mcp add-from-claude-desktop   # Import from desktop app
claude mcp reset-project-choices     # Reset approvals

claude plugin - 插件管理

claude plugin list              # List plugins
claude plugin install <name>    # Install plugin
claude plugin install <name>@marketplace  # From specific marketplace
claude plugin uninstall <name>  # Remove plugin
claude plugin enable <name>     # Enable disabled plugin
claude plugin disable <name>    # Disable plugin
claude plugin update <name>     # Update plugin
claude plugin validate <path>   # Validate manifest
claude plugin marketplace       # Manage marketplaces

claude update - 自我更新

claude update                   # Check and install updates

claude doctor - 诊断

claude doctor                   # Check health/issues

claude install - 原生构建

claude install                  # Install native build
claude install stable           # Specific version
claude install latest           # Latest version

斜杠命令（交互模式）

命令	用途
/init	生成 CLAUDE.md
/clear	重置上下文
/compact	总结对话
/bug	报告问题
/doctor	运行诊断
/model	切换模型
/config	查看/编辑设置
/permissions	管理权限
/memory	查看/编辑记忆
/project:<cmd>	项目专属命令
/user:<cmd>	用户专属命令

自定义命令

创建 .claude/commands/fix-issue.md：

Fix GitHub issue #$ARGUMENTS

1. Read the issue details
2. Identify the problem
3. Implement the fix
4. Write tests
5. Create a commit

用法：/project:fix-issue 1234

配置

用户设置（~/.claude/settings.json）：

{
  "model": "claude-sonnet-4-5-20250929",
  "verbose": false,
  "theme": "dark"
}

项目设置（.claude/settings.json）：

{
  "allowedTools": ["Bash(git:*)", "Read", "Edit"],
  "disallowedTools": ["Bash(rm:*)"]
}

CLI 标志

核心

-p, --print                 Non-interactive mode
-c, --continue              Continue last conversation
-r, --resume <ID>           Resume specific session
-v, --version               Show version

模型与配置

--model <MODEL>             sonnet|opus|haiku or full name
--fallback-model <MODEL>    Fallback when overloaded
--settings <FILE>           Load settings JSON
--setting-sources <LIST>    user,project,local
--session-id <UUID>         Use specific session ID

系统提示词

--system-prompt <TEXT>      Replace default prompt
--append-system-prompt <T>  Append to default
--system-prompt-file <F>    Replace with file (print only)
--append-system-prompt-file Replace with file (print only)

Agent 与工具

--agent <NAME>              Specify agent
--agents <JSON>             Define custom subagents
--tools <LIST>              Restrict built-in tools
--allowedTools <LIST>       Auto-approve tools
--disallowedTools <LIST>    Remove tools from context

权限

--permission-mode <MODE>    acceptEdits|bypassPermissions|default|delegate|dontAsk|plan
--dangerously-skip-permissions  Skip all prompts (DANGEROUS)
--allow-dangerously-skip-permissions  Enable bypass option

输出

--output-format <FMT>       text|json|stream-json
--input-format <FMT>        text|stream-json
--include-partial-messages  Include streaming chunks
--verbose                   Verbose logging
--debug [FILTER]            Debug mode with filtering

高级

--max-turns <N>             Limit agent turns (print only)
--max-budget-usd <AMT>      Spending limit (print only)
--json-schema <SCHEMA>      Validate JSON output
--chrome / --no-chrome      Chrome integration
--ide                       IDE auto-connect
--fork-session              Create new session on resume
--no-session-persistence    Don't save session
--add-dir <DIRS>            Additional directories
--plugin-dir <DIRS>         Load plugins
--disable-slash-commands    Disable all skills
--mcp-config <FILES>        MCP server configs
--strict-mcp-config         Only use specified MCP
--betas <HEADERS>           Beta API headers

自定义子 Agent

claude --agents '{
  "reviewer": {
    "description": "Code reviewer. Use after changes.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

---

常见模式与边缘情况

CI/CD 集成

GitHub Actions 中的 Codex：

- name: Run Codex
  run: |
    echo "${{ secrets.OPENAI_API_KEY }}" | codex login --with-api-key
    codex exec --json -o result.txt "fix linting errors"

CI 中的 Claude：

- name: Run Claude
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p --output-format json "review this PR" > review.json

处理速率限制

**Codex：**内置自动退避。

**Claude：**使用 --fallback-model：

claude -p --fallback-model haiku "quick task"

处理大型代码库

# Codex: Use /compact to free context
# In session: /compact

# Claude: Use /compact or start fresh
claude --no-session-persistence -p "analyze src/"

多目录访问

# Codex
codex --add-dir ../shared-lib --add-dir ../config

# Claude
claude --add-dir ../shared-lib ../config

结构化输出

Codex：

codex exec --output-schema schema.json "generate API spec"

Claude：

claude -p --json-schema '{"type":"object","properties":{"name":{"type":"string"}}}' "extract data"

图像输入

Codex：

codex -i screenshot.png "explain this UI"
codex -i img1.png -i img2.png "compare these"

Claude：

# Via file reference in prompt
claude "analyze the image at ./screenshot.png"

会话分叉

# Codex: /fork in session

# Claude
claude -r "session-id" --fork-session "try alternative approach"

MCP 服务调试

Codex：

codex mcp list --json | jq .

Claude：

claude --debug "mcp" --mcp-config ./mcp.json

---

故障排除

身份验证问题

问题	Codex	Claude
未登录	codex login status	claude doctor
令牌已过期	codex logout && codex login	claude setup-token
API 密钥问题	检查 OPENAI_API_KEY	检查 ANTHROPIC_API_KEY

沙盒问题

问题	解决方案
权限被拒绝	对特定目录使用 --add-dir
无法运行命令	检查沙盒模式，使用 workspace-write
网络被阻止	沙盒可能会阻止网络；谨慎使用 danger-full-access

MCP 服务问题

问题	解决方案
未找到服务	检查 mcp list，确认已安装
连接失败	检查服务日志，确认 URL/命令无误
需要身份验证	使用 mcp login（Codex）或添加请求头（Claude）

性能问题

问题	解决方案
响应缓慢	使用更轻量的模型（gpt-4.1-mini / haiku）
上下文溢出	使用 /compact 进行总结
成本过高	设置 --max-budget-usd（Claude）

---

最佳实践

1. 从只读模式开始进行探索，按需提升权限
2. 使用会话——恢复工作，而不是重新开始
3. 创建 AGENTS.md/CLAUDE.md，写明项目专属说明
4. 利用 MCP 服务进行外部集成
5. 在 CI/CD 中使用结构化输出，便于解析
6. 使用 --max-budget-usd 设置支出上限
7. 应用更改前检查差异（/diff、codex cloud diff）
8. 进行重大更改前提交检查点