AI Agent 配置指南

V2EX AI Persona 提供兼容 OpenAI Chat Completions 的接口，并支持工具调用。你可以把它接入支持 OpenAI 兼容 Provider 的 AI Agent，让 Agent 在你的电脑上读取文件、修改代码和执行命令。

下面以 OpenCode、Claude Code 和 Pi 为例。接口的完整行为和参数以 AI 角色设定 API 文档为准。

开始之前

在 Token 设置中创建一个 Personal Access Token。Token 只会在创建后的有限时间内完整显示，请妥善保存，不要把它提交到代码仓库或发给他人。
OpenAI 兼容接口的 Base URL 是 https://edge.v2ex.com/chat/v1。
模型名可以使用公共角色设定 coder，也可以使用你有权访问的其他公开角色设定，或自己创建的角色设定的名称。
网页端 AI Chat 和 Agent 共用账号的 AI Chat 配额与并发限制。

配置 Agent 前，可以先在 Terminal 中确认网络和 Token 都能访问接口：

curl -sS \
  -H "Authorization: Bearer YOUR_V2EX_ACCESS_TOKEN" \
  "https://edge.v2ex.com/chat/v1/models"

请把 YOUR_V2EX_ACCESS_TOKEN 替换成自己的 Token。如果请求返回可用角色设定列表，说明 Base URL、网络和认证都可以正常工作。

OpenCode

在 OpenCode 的配置文件 ~/.config/opencode/opencode.jsonc 中加入一个 V2EX Provider：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "v2ex": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "V2EX",
      "options": {
        "baseURL": "https://edge.v2ex.com/chat/v1"
      },
      "models": {
        "coder": {}
      }
    }
  }
}

启动 OpenCode，输入 /connect。
选择 Other，输入与配置一致的 Provider ID v2ex，并在提示时输入 Personal Access Token。Token 不需要写进 opencode.jsonc。
输入 /models，选择 v2ex/coder。

要使用自己的角色设定，请把配置中 models 下面的 coder 替换成角色设定名称，然后重新选择对应模型。

Claude Code

Claude Code 使用 Anthropic 协议，不能直接连接 OpenAI 兼容接口。可以在本机运行 CLIProxyAPI 完成协议转换。如果你已经有一套正常工作的 Claude Code 环境，建议先在独立环境中测试，避免覆盖原有配置。

1. 配置 CLIProxyAPI

macOS 可以使用 Homebrew 安装并启动：

brew install cliproxyapi
brew services start cliproxyapi

打开 http://localhost:8317/management.html，把 V2EX 添加为「OpenAI 兼容」Provider：

服务地址：https://edge.v2ex.com/chat/v1
模型名：coder，或你的角色设定名称
API Key：你的 V2EX Personal Access Token

同时在 CLIProxyAPI 中设置一个供本机客户端访问代理的 API Token。这个代理 Token 和 V2EX Personal Access Token 是两个不同的值。

2. 启动 Claude Code

安装 Claude Code 后，在启动 claude 的同一个 Shell 中设置以下环境变量。把 YOUR_CLIPROXYAPI_TOKEN 换成 CLIProxyAPI 中设置的代理 Token：

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=YOUR_CLIPROXYAPI_TOKEN

export ANTHROPIC_DEFAULT_OPUS_MODEL=coder
export ANTHROPIC_DEFAULT_SONNET_MODEL=coder
export ANTHROPIC_DEFAULT_HAIKU_MODEL=coder

claude

ANTHROPIC_BASE_URL 把请求发送到本机代理，ANTHROPIC_AUTH_TOKEN 以 Bearer Token 认证代理。三个 ANTHROPIC_DEFAULT_*_MODEL 变量把 Claude Code 的 Opus、Sonnet 和 Haiku 模型族都映射到 CLIProxyAPI 中配置的 coder；其中 Haiku 映射也会用于部分后台请求。这里不需要设置已弃用的 ANTHROPIC_SMALL_FAST_MODEL，也不需要强制覆盖子 Agent 模型。变量的当前含义可以参考 Claude Code 环境变量文档和模型配置文档。

Claude Code 的 /usage 可能会把这个自定义模型显示为未知模型，这不影响请求通过代理发送到所配置的角色设定。

Pi Coding Agent

安装 Pi 后，打开 ~/.pi/agent/models.json，加入 V2EX Provider：

{
  "providers": {
    "v2ex": {
      "baseUrl": "https://edge.v2ex.com/chat/v1",
      "api": "openai-completions",
      "apiKey": "YOUR_V2EX_ACCESS_TOKEN",
      "models": [
        {
          "id": "coder",
          "name": "GLM-5.2",
          "contextWindow": 1000000,
          "input": ["text"],
          "reasoning": true
        },
        {
          "id": "coder-m3",
          "name": "MiniMax-M3",
          "contextWindow": 524288,
          "input": ["text", "image"],
          "reasoning": true
        },
        {
          "id": "coder-ds4",
          "name": "DeepSeek-V4-Pro",
          "contextWindow": 524288,
          "input": ["text"],
          "reasoning": true
        }
      ]
    }
  }
}

启动 Pi 后，使用 /model 在 coder、coder-m3 和 coder-ds4 之间切换。请限制这个配置文件的读取权限，并避免同步或提交其中的 Token。

故障排查

Terminal 中无法连接：浏览器和命令行可能使用不同的代理设置。先运行本页开头的 curl；如果超时，请检查 Terminal 的网络和代理配置。
401 或认证失败：检查 Token 是否完整、是否已过期，以及 Agent 或代理发送的是 V2EX Personal Access Token。
找不到模型：调用 /models 确认当前 Token 可以访问的角色设定名称，并保持大小写一致。角色设定需要有非空的上下文。
429：查看 AI Chat 配额和响应中的配额、频率限制 Header，等待相应窗口恢复后重试。
Claude Code 无法连接代理：先确认 CLIProxyAPI 正在监听 127.0.0.1:8317，再检查 ANTHROPIC_AUTH_TOKEN 使用的是代理 Token，而不是把两个 Token 混用。

权限与安全

V2EX 接口只负责生成模型响应，不会代替客户端执行命令。文件读取、代码修改和命令执行都发生在 Agent 所在的电脑上，并受该 Agent 自身的权限、确认规则和沙箱控制。运行前请检查工作目录与授权范围，不要让 Agent 接触不必要的凭据或重要文件。